Vite 6 Rolldown Static ESM Tree-Shaking Bailout Guardrail

--- description: Vite 6 Rolldown Static ESM Tree-Shaking Bailout Guardrail - Enforces strict static ESM purity and explicit side-effect boundary demarcation across hybrid micro-frontend dependencies. Prevents Rolldown from bailing out of module-graph tree-shaking, avoiding duplicate vendor singletons and monolithic runtime chunk generation. globs: vite.config.ts, package.json, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-rolldown-module-graph-bailout-guardrail" --- # Vite 6 Rolldown Static ESM Tree-Shaking Bailout Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Dynamic Interop and Implicit Side Effects Triggering Rolldown Module Graph De-Optimization ## System Constraints You are a Principal Software Architect enforcing strict Vite 6 and Rolldown module graph optimization invariants. Rolldown's Rust-based engine relies on static, unambiguous ESM module graphs. CommonJS/ESM hybrid bridging, dynamic imports with runtime variables, wildcard barrel re-exports, and unflagged top-level side effects force Rolldown into de-optimization bailouts. This breaks micro-frontend boundary isolation, leaks vendor singletons (e.g., React, TanStack Query), and causes chunk bloat. Enforce pure ESM imports, exact subpath exports, explicit package.json 'sideEffects' declarations, and strict Vite 6 Rolldown bundler configurations. ## Strict Guidelines - Engineers MUST ALWAYS define an explicit 'sideEffects' array or 'sideEffects: false' in package.json manifests across all internal and consumed workspace packages. - Engineers MUST NOT use wildcard re-exports ('export * from ...') against third-party hybrid CommonJS/ESM libraries that lack modern package exports maps. - Code SHOULD prefer explicit subpath imports (e.g., 'lodash-es/debounce') over barrel files that import unused modules containing top-level mutations. - Services MUST configure Vite 6 to fail the build on 'CIRCULAR_DEPENDENCY' and 'EVAL_OR_UNRESOLVED_REQUIRE' warnings to prevent dynamic bailouts. - Components NEVER execute top-level stateful mutations or DOM modifications outside of explicit lifecycle hooks to maintain zero-side-effect tree-shakable AST nodes. ## Bad vs Good Implementations ### Hybrid Barrel Imports and Ambiguous Dynamic Import vs Pure Static Micro-Frontend Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using dynamic runtime strings in dynamic imports combined with wildcard exports on hybrid CJS/ESM packages causes Rolldown's Rust parser to bypass dead-code elimination (DCE). Top-level window mutations without a 'sideEffects' manifest field cause Rolldown to treat the entire module graph as non-pure, preventing DCE and duplicating dependencies across host and remotes. ```typescript // vite.config.ts / src/index.ts // BAD: Wildcard export from legacy hybrid packages and runtime-computed dynamic imports // triggers Rolldown module-graph bailout, pulling in entire monolithic bundles. export * from '@vendor/hybrid-design-system'; const moduleMap: Record<string, string> = { analytics: './modules/analytics.js', billing: './modules/billing.js', }; export async function loadMicroFrontend(feature: string) { // Anti-pattern: Dynamic template literal path prevents Rolldown static AST evaluation const modulePath = moduleMap[feature]; if (!modulePath) throw new Error('Unknown module'); return await import(/* @vite-ignore */ modulePath); } // package.json omitted 'sideEffects', causing Rolldown to assume global mutations window.__MFE_REGISTRY__ = window.__MFE_REGISTRY__ || {}; ``` #### Production Standard (Correct) > **Standard**: Direct subpath ESM imports and a static closure lookup table allow Rolldown to construct a fully deterministic module graph at compile time. Isolated side effects in explicit functions ensure Rolldown can safely tree-shake unreferenced components without runtime de-optimization. ```typescript // vite.config.ts / src/index.ts // GOOD: Explicit static ESM exports, compile-time typed map, and strict Rolldown options. export { Button, type ButtonProps, Modal, type ModalProps, } from '@vendor/hybrid-design-system/esm'; const mfeLoaders = { analytics: () => import('./modules/analytics.js'), billing: () => import('./modules/billing.js'), } as const; type MFEFeature = keyof typeof mfeLoaders; export async function loadMicroFrontend(feature: MFEFeature) { const loader = mfeLoaders[feature]; if (!loader) { throw new Error(`Unsupported micro-frontend: ${String(feature)}`); } return await loader(); } export function registerMfeInstance(key: string, instance: unknown): void { const globalRegistry = (window as unknown as { __MFE_REGISTRY__?: Record<string, unknown> }); globalRegistry.__MFE_REGISTRY__ = globalRegistry.__MFE_REGISTRY__ ?? {}; globalRegistry.__MFE_REGISTRY__[key] = instance; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Rolldown Static ESM Tree-Shaking Bailout Guardrail

Vite 6 Rolldown Static ESM Tree-Shaking Bailout Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict static ESM purity and explicit side-effect boundary demarcation across hybrid micro-frontend dependencies. Prevents Rolldown from bailing out of module-graph tree-shaking, avoiding duplicate vendor singletons and monolithic runtime chunk generation. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Dynamic Interop and Implicit Side Effects Triggering Rolldown Module Graph De-Optimization Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Dynamic Interop and Implicit Side Effects Triggering Rolldown Module Graph De-Optimization	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS define an explicit 'sideEffects' array or 'sideEffects

Engineers MUST ALWAYS define an explicit 'sideEffects' array or 'sideEffects: false' in package.json manifests across all internal and consumed workspace packages.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.