Skip to content

PostCSS plugin should not invoke CLI init during build #24

@Austin1serb

Description

@Austin1serb

Summary

@react-zero-ui/core currently mixes two responsibilities inside the PostCSS runtime:

  1. generating Zero UI CSS / attribute artifacts
  2. running project initialization and config patching

That design causes the PostCSS entry to cross into CLI setup code during a Next.js build, which should never happen.

Exact boundary

The problematic path is:

  • src/postcss/index.cts compiles to dist/postcss/index.cjs
  • that CJS PostCSS entry imports runZeroUiInit from ../cli/postInstall.js
  • postInstall.js is ESM inside a "type": "module" package

So the compiled CommonJS PostCSS plugin ends up pulling in CLI initialization code during CSS compilation.

Newer Next / Node build paths are stricter about this boundary and can fail when the build pipeline hits it.

Why this is a bug

The PostCSS plugin should only do PostCSS work:

  • scan source files
  • generate CSS variants
  • generate .zero-ui/attributes.*
  • register dependencies for rebuilds

It should not:

  • patch postcss.config.*
  • patch tsconfig.json
  • patch Next layout/body files
  • run install/setup/init logic during a build

The CLI setup path belongs behind an explicit user action such as npx create-zero-ui, not inside CSS compilation.

Expected behavior

During a Next.js build, @react-zero-ui/core/postcss should be runtime-safe and should not invoke CLI initialization logic.

Current behavior

The PostCSS plugin auto-initializes on first run when isZeroUiInitialized() is false, which causes config mutation and pulls CLI setup code into the build path.

Proposed fix

  1. Remove the runZeroUiInit import from src/postcss/index.cts
  2. Remove the auto-init block from the PostCSS plugin
  3. Keep initialization / patching in the explicit CLI entry only
  4. If first-run guidance is still desired, emit a warning instead of mutating the project during the build

Notes

isZeroUiInitialized() may still be useful as an artifact-existence check, but it should not be used to decide whether the PostCSS plugin should run CLI setup.

The key architectural rule is: the CLI can initialize a project, but the PostCSS plugin should never run the CLI during a build.

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions