@hile/rsc-build

Production build tooling for @hile/rsc: directive analysis, immutable plugin compilation, shared React client shims, build configuration, and the hile-rsc artifact CLI. It has no service lifecycle or development watcher responsibilities.

Builds are transactional: all graphs and the manifest are completed in a sibling staging directory and atomically published only after success. A failed build leaves the requested immutable output directory empty and retryable for the same build ID.

RscModuleGraph is shared by production and incremental compilation. Reference source generation and artifact assembly live in separate modules, so directive semantics, chunk manifests, CSS artifacts, integrity values and Server Function bundles have one implementation.

Browser compilation respects dependency browser replacements and disabled modules. Remaining Node built-in imports become empty CommonJS modules so dependencies can select their browser fallbacks; this provides no Node API polyfills. Explicit esbuild aliases take precedence, and missing alias targets still fail. Disabled modules do not register RSC references or trigger directive validation failures; ambiguous exclusions are confirmed by an isolated native esbuild build without executing source or writing files. Exclusion metadata refreshes on each incremental build. Node/SSR imports remain native, unresolved required dependencies still fail, and optional require() calls guarded by try/catch retain esbuild's normal behavior. Lazy chunks use hash-based filenames that satisfy artifact path validation even when source names contain spaces.

Production builds minify browser and SSR client graphs, including their lazy chunks and imported CSS, and compile both targets with process.env.NODE_ENV set to "production". This removes development-only dependency code and keeps SSR and browser environment branches aligned. Incremental development compilation remains unminified. Artifact sizes and integrity values describe the final emitted bytes; rebuild plugins with a new immutable build ID to adopt this optimization.

Every build records artifact byte sizes and analyzes all declared route exports in one build to emit their reachable browser client-reference IDs. Client-graph CSS is marked client-scoped and linked to the client references that reach it; configured shared CSS is marked plugin-wide. Routes default to the safe assets preload policy; set prefetch: "none" to disable proactive loading or prefetch: "route" only when the route's Flight render is side-effect free and may be prefetched by a Host. Dependency, style-scope, and size metadata are build output and must not be authored in configuration.

Use

hile-rsc build
hile-rsc inspect
hile-rsc verify

The common commands default to hile-rsc.json, .hile-rsc, and the runtime tuple supported by the installed @hile/rsc. Explicit paths, --config, and the complete --react/--react-dom/--rsc tuple remain available for automation and compatibility checks.

buildId is the immutable identity for one deployment. When omitted in config, it is auto-generated and can be overridden by RSC_BUILD_ID; output is placed under the configured outdir with the resolved buildId. inspect and verify accept either one artifact directory or its build root and select the newest generated build. An explicit buildId keeps the existing exact-outdir behavior. The validated config, directive rules, artifact layout, and full Host/plugin walkthrough are documented in docs/ai/packages/rsc.md and docs/ai/recipes/rsc-plugin-host.md.

Optional metadata is validated and emitted into the same immutable plugin.json. Navigation paths must reference declared plugin routes; public URL and visibility policy remain Host-owned. build, inspect, and verify expose the canonical metadata for automation.

A route may declare metadataEntry to name a server-entry export that resolves dynamic document metadata. The compiler records only that export identity; @hile/rsc executes it as bounded data through the same exact-build route and Context boundary as rendering. The Host application owns the returned field schema and all framework-specific head behavior.

Optional build-scoped CSS can be declared through styles. Each value is either an explicit relative path such as ./src/theme.css, an absolute path, or a package export such as @example/ui/theme.css. The compiler content-hashes and deduplicates these files, copies them once below the immutable artifact's styles/ directory, and records SHA-256 integrity in plugin.json. These inputs must be self-contained CSS: relative url() dependencies and external @import files are not copied or rewritten. Client-graph CSS remains supported and is appended after build-scoped styles.