signaltree: Instructions file for GitHub Copilot

SignalTree Build & Packaging Directive

Context

Historical issues with the Nx @nx/js:tsc pipeline and ad-hoc post-build copy scripts allowed incomplete dist/ folders to be published. To eliminate this failure mode permanently, all SignalTree libraries must ship using a bundler that emits the final publishable layout directly. The chosen strategy is to adopt an ESM-preserving bundler configuration (e.g. tsup, Rollup, or esbuild) with preserveModules enabled so tree-shaking remains fully effective.

Mandatory Approach

• Executor: Use an Nx bundler executor (@nx/rollup:rollup, @nx/esbuild:esbuild, or equivalent) instead of @nx/js:tsc for publishable packages.
• Module Format: Emit pure ESM with preserveModules: true (or the equivalent flag). The bundler must generate one output file per source module (e.g. dist/enhancers/batching/index.js), preserving compatibility with consumer tree-shaking.
• Output Layout: Configure the bundler so dist/ contains the final artifacts referenced by each package manifest (main, module, types, exports). Manual src -> dist copy steps are forbidden.
• Consolidated Target: Each package’s build target must be a single bundler invocation that produces ready-to-publish output. No separate “post-build” scripts are allowed.
• Release Hook: Workspace release automation must rely solely on these bundler-based build targets. Additional file-system manipulations (copying, pruning) require explicit justification and review.

Required Optimizations

When configuring the bundler, enable production optimizations that TypeScript’s compiler does not provide:

• Strip stray debugger statements and unintentional console logging from production bundles where appropriate.
• Define __DEV__ = false (or similar guard) so dead dev-only branches can be removed.
• Emit consolidated .d.ts bundles (dts: true, Rollup @rollup/plugin-typescript, etc.) matching the preserved module layout.

Library exception — do NOT blanket drop: ['console']. We publish a library, not an app. SignalTree's [ST####] developer guardrails are intentional console.warn/console.error calls guarded by if (typeof ngDevMode === 'undefined' || ngDevMode) (or an opt-in config flag like debugMode). Those guards let the consumer's production build strip the warnings (Angular elides ngDevMode blocks) while dev builds keep them — which is the whole point of the AI-discoverability guardrail feature. Adding drop: ['console'] to our build would delete those warnings for everyone, including dev consumers, and silently regress the feature. Correct policy: every dev-only console.* in published src/ must be ngDevMode-guarded (or config-gated); genuine catch-block error reporting may remain. Enforce that guarding instead of dropping console at our build step.