Vite 6 and Rolldown Deterministic Module Chunk Boundary Isolation Standard

--- description: Vite 6 and Rolldown Deterministic Module Chunk Boundary Isolation Standard - Enforces deterministic AST-driven chunking boundaries and explicit module isolation in Vite 6 with Rolldown. Prevents cascading edge CDN cache invalidations across federated micro-frontends caused by non-deterministic dynamic chunking, circular import graphs, and leaky barrel exports. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-rolldown-deterministic-chunking-standard" --- # Vite 6 and Rolldown Deterministic Module Chunk Boundary Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Implicit Dynamic Splitting Inducing Cascading Edge Cache Invalidation Across Micro-Frontends ## System Constraints You are a Principal Software Architect enforcing deterministic module chunking and edge cache longevity for Vite 6 and Rolldown. You must eliminate all nondeterministic manualChunks callbacks, prevent re-export barrel pollution that destabilizes module graphs, and mandate strict content-addressed chunk boundaries for micro-frontend edge deployments. ## Strict Guidelines - Engineers MUST ALWAYS declare deterministic manual chunk allocations via strict package-name AST lookups rather than heuristic regex matches on dynamic paths. - Engineers MUST NOT export or import through monolithic barrel files (`index.ts`) in asynchronous or federated boundaries, as they unify disconnected AST graphs into mutated shared chunks. - Build configurations MUST specify deterministic hash algorithms and chunk naming conventions (`[name].[hash:16].js`) with Rolldown-compatible output options. - Shared runtime dependencies across micro-frontends (e.g., React runtime, state primitives) MUST be isolated into discrete, immutable leaf chunks to preserve edge CDN cache hits. - Dynamic imports MUST define explicit chunk names or boundary constraints to prevent Rolldown from synthetically coalescing lazy routes into volatile shared entry chunks. - Engineers MUST verify circular dependency absence prior to compilation; circular references force Rolldown to merge distinct module boundaries into non-deterministic mega-chunks. ## Bad vs Good Implementations ### Vite 6 Rolldown Chunking Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Grouped node_modules into a monolithic 'vendor' chunk that invalidates globally on any single library patch, while arbitrarily grouping components into a single mutable chunk without cryptographic content hashing. ```typescript import { defineConfig } from 'vite'; export default defineConfig({ build: { rollupOptions: { output: { // Flawed: non-deterministic regex matching and arbitrary chunk names manualChunks(id) { if (id.includes('node_modules')) { // Creates a giant unstable chunk that busts cache on ANY dep upgrade return 'vendor'; } if (id.includes('src/components')) { // Merges leaf components across routes into a volatile shared chunk return 'components'; } }, chunkFileNames: 'assets/[name].js' } } } }); ``` #### Production Standard (Correct) > **Standard**: Implements deterministic AST-level package isolation using an explicit vendor manifest with content-addressed 16-character hashes, preserving edge cache longevity for micro-frontend consumers. ```typescript import { defineConfig } from 'vite'; const VENDOR_ISOLATION_MANIFEST: Record<string, string> = { react: 'runtime-framework', 'react-dom': 'runtime-framework', 'lucide-react': 'ui-icons', '@tanstack/react-query': 'data-cache' }; export default defineConfig({ build: { rolldownOptions: { output: { chunkFileNames: 'chunks/[name].[hash:16].mjs', entryFileNames: 'entries/[name].[hash:16].mjs', assetFileNames: 'assets/[name].[hash:16].[ext]', manualChunks(id) { if (!id.includes('node_modules/')) { return undefined; } const parts = id.split('node_modules/')[1].split('/'); const pkgName = parts[0].startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0]; if (pkgName in VENDOR_ISOLATION_MANIFEST) { return VENDOR_ISOLATION_MANIFEST[pkgName]; } return 'vendor-isolated-core'; } } } } }); ``` ### Decoupled Asynchronous Micro-Frontend Routing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing from a shared feature barrel file introduces transitive AST nodes into the route boundary, bundling heavyweight analytics dependencies into the critical initial chunk and forcing cache invalidation across unrelated feature updates. ```typescript // Anti-pattern: Barrel file import pulls unwanted sub-modules into route AST import { DashboardGrid, UserSettingsModal, HeavyAnalyticsChart } from '@/features'; export default function Route() { return <DashboardGrid />; } ``` #### Production Standard (Correct) > **Standard**: Uses direct path imports with deterministic dynamic import boundaries, isolating the chunk AST and guaranteeing edge caches remain valid when adjacent feature components change. ```typescript import React, { Suspense, lazy } from 'react'; // Deterministic boundary: direct path import bypasses barrel index traversal const DashboardGrid = lazy(() => import( /* webpackChunkName: "feat-dashboard-grid" */ '@/features/dashboard/DashboardGrid' ).then(m => ({ default: m.DashboardGrid })) ); export default function Route() { return ( <Suspense fallback={<div className="animate-pulse h-96" />}> <DashboardGrid /> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 and Rolldown Deterministic Module Chunk Boundary Isolation Standard

Vite 6 and Rolldown Deterministic Module Chunk Boundary Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic AST-driven chunking boundaries and explicit module isolation in Vite 6 with Rolldown. Prevents cascading edge CDN cache invalidations across federated micro-frontends caused by non-deterministic dynamic chunking, circular import graphs, and leaky barrel exports. 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: Implicit Dynamic Splitting Inducing Cascading Edge Cache Invalidation Across Micro-Frontends 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	Implicit Dynamic Splitting Inducing Cascading Edge Cache Invalidation Across Micro-Frontends	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 declare deterministic manual chunk allocations via strict package-name AST lookups rather than heuristic regex matches on dynamic paths.

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.