Vite 6 & Rolldown: Deterministic Chunk Isolation and Pure Tree-Shaking

--- description: Vite 6 & Rolldown: Deterministic Chunk Isolation and Pure Tree-Shaking - Enforces strict module boundary isolation, explicit tree-shaking annotations, and deterministic chunk distribution for Vite 6 powered by Rolldown. Eliminates circular dependency deadlocks and barrel file cascades to guarantee sub-50ms hot module replacement (HMR) and zero-vendor dead-code leakage in Rust-native build pipelines. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, package.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-rolldown-chunk-isolation-treeshaking" --- # Vite 6 & Rolldown: Deterministic Chunk Isolation and Pure Tree-Shaking > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Barrel Re-Exports and Unmarked Side-Effects Poisoning Rolldown Module Invalidation Graph ## System Constraints You are a Principal Engineer enforcing Vite 6 Rolldown Deterministic Chunk Isolation & Tree-Shaking. Mandate invariants regarding strict module boundaries, zero-barrel imports for code-split features, explicit side-effects annotations, and deterministic chunking configs to preserve sub-50ms HMR and optimal dead-code elimination. ## Strict Guidelines - Engineers MUST ALWAYS annotate non-trivial top-level constant evaluations and factory invocations with /* @__PURE__ */ to allow Rolldown's Rust tree-shaker to drop unused tokens. - Engineers MUST NOT import through aggregative barrel files ('index.ts') when referencing heavy domain features, UI components, or third-party libraries (e.g., lucide-react, lodash-es). - Code MUST avoid circular dependencies entirely; circular dependencies force Rolldown to merge modules into monolithic fallback chunks and destroy sub-50ms HMR propagation. - Services MUST declare explicit dynamic imports (React.lazy or import()) at routing boundaries to establish deterministic chunk boundaries across Rust compilation passes. - Components NEVER execute global side-effects at the root module scope; all stateful registration or listener attachment MUST be deferred to lifecycle hooks or explicit init calls. - Engineers MUST specify 'sideEffects': false or an explicit file array in package.json to prevent dead code retention during production Rolldown emission. ## Bad vs Good Implementations ### Barrel File Pollution vs. Granular Leaf Import with Pure Annotation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing from aggregate barrel files forces Rolldown to parse and link hundreds of unrelated modules into the HMR graph. The top-level `heavyCompute` execution without pure annotations forces the compiler to retain the entire evaluation path even if unused, causing bundle bloat and sub-optimal HMR re-transformation. ```typescript // src/features/dashboard/AnalyticsCard.tsx // Anti-pattern: Barrel import invalidates entire icon/component graph and breaks HMR scoping import { BarChart, MetricWidget, heavyCompute } from '@/components'; import { formatCurrency } from '@/utils'; // Module-level invocation prevents Rolldown from tree-shaking this unused calculation const DEFAULT_METRIC = heavyCompute({ sampleRate: 1.0 }); export const AnalyticsCard = () => ( <div> <MetricWidget value={formatCurrency(100)} /> <BarChart /> </div> ); ``` #### Production Standard (Correct) > **Standard**: Importing directly from leaf paths allows Rolldown to construct a fine-grained directed acyclic graph (DAG). The /* @__PURE__ */ annotation signals to the Rust backend that the expression can be discarded if unreferenced. HMR invalidation is scoped exclusively to the modified leaf file, sustaining sub-50ms reload latencies. ```typescript // src/features/dashboard/AnalyticsCard.tsx // Production invariant: Direct leaf imports ensure granular HMR boundaries import { BarChart } from '@/components/charts/BarChart'; import { MetricWidget } from '@/components/widgets/MetricWidget'; import { formatCurrency } from '@/utils/currency/formatCurrency'; import type { ComputeOptions } from '@/utils/analytics/types'; // Explicit pure annotation enables Rolldown Rust AST optimizer to safely eliminate dead code const DEFAULT_METRIC = /* @__PURE__ */ (() => ({ sampleRate: 1.0, timestamp: 0, }))(); export const AnalyticsCard = () => ( <div> <MetricWidget value={formatCurrency(100)} fallback={DEFAULT_METRIC} /> <BarChart /> </div> ); ``` ### Vite 6 Rolldown Configuration for Deterministic Chunks #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Lumping all dependencies into a monolithic 'vendor' chunk negates Rolldown's parallel tree-shaking capabilities, forces massive re-downloads on minor dependency changes, and causes cross-module dependency tangling that destabilizes HMR updates. ```typescript // vite.config.ts import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], build: { // Anti-pattern: Undefined or arbitrary chunking causes non-deterministic chunk // pollution and cyclical vendor bloat under Rolldown rollupOptions: { output: { manualChunks: (id) => { if (id.includes('node_modules')) { return 'vendor'; // Single massive vendor chunk destroys cache & tree-shaking } }, }, }, }, }); ``` #### Production Standard (Correct) > **Standard**: Leverages fine-grained, deterministic manual chunks that isolate critical framework runtime from feature modules. Strict treeshake options instruct Rolldown to respect purity annotations, prune unused transitive dependencies, and maintain isolated module graphs needed for instantaneous HMR. ```typescript // vite.config.ts import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], build: { target: 'esnext', modulePreload: { polyfill: false }, rolldownOptions: { output: { // Production invariant: Explicit vendor grouping prevents circular chunk contamination manualChunks(id) { if (id.includes('node_modules/react') || id.includes('node_modules/react-dom')) { return 'framework'; } if (id.includes('node_modules/@tanstack/react-query')) { return 'data-layer'; } }, chunkFileNames: 'assets/[name]-[hash].js', compact: true, }, treeshake: { moduleSideEffects: 'no-external', annotations: true, correctVarValueBeforeDeclaration: true, }, }, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 & Rolldown: Deterministic Chunk Isolation and Pure Tree-Shaking

Vite 6 & Rolldown: Deterministic Chunk Isolation and Pure Tree-Shaking defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module boundary isolation, explicit tree-shaking annotations, and deterministic chunk distribution for Vite 6 powered by Rolldown. Eliminates circular dependency deadlocks and barrel file cascades to guarantee sub-50ms hot module replacement (HMR) and zero-vendor dead-code leakage in Rust-native build pipelines. 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: Monolithic Barrel Re-Exports and Unmarked Side-Effects Poisoning Rolldown Module Invalidation Graph 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	Monolithic Barrel Re-Exports and Unmarked Side-Effects Poisoning Rolldown Module Invalidation Graph	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 annotate non-trivial top-level constant evaluations and factory invocations with /* @PURE */ to allow Rolldown's Rust tree-shaker to drop unused tokens.

Engineers MUST ALWAYS annotate non-trivial top-level constant evaluations and factory invocations with /* @__PURE__ */ to allow Rolldown's Rust tree-shaker to drop unused tokens.

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.