Rolldown Deterministic Module Chunking & Federated Edge Invariant

--- description: Rolldown Deterministic Module Chunking & Federated Edge Invariant - Enforces byte-for-byte reproducible bundle hashes, topological module ordering, and shared-dependency singleton deduplication across federated Vite 6 and Rolldown edge builds. Prevents module identity drift, dual-package hazard at runtime edge nodes, and volatile chunk graph invalidations caused by non-deterministic dynamic chunk allocation. globs: vite.config.{ts,js,mjs}, rolldown.config.{ts,js,mjs}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rolldown-deterministic-module-chunking-invariant" --- # Rolldown Deterministic Module Chunking & Federated Edge Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Non-Deterministic Dynamic Chunk Splitting and Platform-Dependent Path Ingestion ## System Constraints You are a Principal Software Architect enforcing deterministic module chunking and strict hash reproducibility under Rolldown and Vite 6. You must mandate canonicalized module paths, deterministic manual chunk assignment, exact version singleton deduplication for federated micro-frontends, and eliminate any runtime or platform-specific variance in generated edge artifacts. ## Strict Guidelines - Engineers MUST ALWAYS normalize all module file paths to POSIX standard before chunk assignment evaluation to eliminate OS-level hashing discrepancies. - Engineers MUST NOT use unanchored substring matching on `node_modules` paths in `manualChunks` functions; exact package specifier parsing via scoped regex or canonical package lookup is mandatory. - Code MUST explicitly enforce singleton scope and deterministic fallback handling for shared federated dependencies (e.g., `react`, `react-dom`, `@tanstack/react-query`) across edge nodes. - Services MUST configure Rolldown output with explicit content-based hash algorithms, uniform `hashCharacters`, and deterministic module sorting flags. - Components NEVER import shared micro-frontend libraries via dynamic template strings with runtime interpolations, as this forces Rolldown to generate unpredictable chunk topologies. - Engineers MUST ensure shared chunks between independent edge builds share identical canonical entry names and dependency graphs to ensure edge CDN deduplication. ## Bad vs Good Implementations ### Vite 6 / Rolldown Deterministic manualChunks Resolution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Splitting by raw string 'node_modules/' fails on Windows (uses backslashes), misidentifies nested dependencies or scoped packages (@scope/pkg), and creates unstable, environment-dependent chunk names that invalidate byte-for-byte reproducibility across edge deployments. ```typescript import { defineConfig } from 'vite'; export default defineConfig({ build: { rollupOptions: { output: { // ANTI-PATTERN: Non-deterministic chunk splitting, unnormalized paths, // and unpredictable chunk output names break federation caching. manualChunks(id) { if (id.includes('node_modules')) { // Vulnerable to OS path separators and non-deterministic package hoisting const parts = id.split('node_modules/')[1].split('/'); return parts[0]; } }, chunkFileNames: 'assets/[name]-[hash].js', }, }, }, }); ``` #### Production Standard (Correct) > **Standard**: Normalizes platform path separators, precisely extracts scoped package identities, guarantees isolated singleton chunks for critical runtime shared modules, and enforces standard hash lengths for byte-for-byte build reproducibility. ```typescript import { defineConfig } from 'vite'; import { createHash } from 'node:crypto'; import path from 'node:path'; // Canonical vendor package parser matching exact scope boundaries const PACKAGE_REGEX = /[\\/]node_modules[\\/](?:(@[^\\/]+)[\\/])?([^\\/]+)/; export default defineConfig({ build: { target: 'esnext', sourcemap: false, rollupOptions: { output: { hashCharacters: 'base64', chunkFileNames: 'chunks/[name].[hash:16].js', entryFileNames: 'entries/[name].[hash:16].js', manualChunks(id: string): string | void { const normalizedPath = id.split(path.win32.sep).join(path.posix.sep); const match = normalizedPath.match(PACKAGE_REGEX); if (!match) return undefined; const [, scope, name] = match; const packageName = scope ? `${scope}/${name}` : name; // Deterministic core singleton isolation if (['react', 'react-dom'].includes(packageName)) { return 'vendor-react-core'; } // Coalesce remaining dependencies deterministically return 'vendor-shared'; }, }, }, }, }); ``` ### Federated Edge Shared-Module Contract Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Untyped runtime access and uncoordinated shared scopes lead to multiple React runtime instantiations at the edge, differing bundle hashes across builds, and broken deduplication. ```typescript // ANTI-PATTERN: Dynamic federation import with variable path and no singleton guarantee export async function loadFederatedModule(scope: string, moduleName: string) { // Edge bundler cannot trace graph statically, creating randomized chunk boundaries const container = (window as any)[scope]; await container.init((window as any).__federation_shared__); const factory = await container.get(`./${moduleName}`); return factory(); } ``` #### Production Standard (Correct) > **Standard**: Defines an explicit shared dependency contract with version pinning and singleton enforcement, ensuring all edge-rendered remotes resolve to identical byte-hashed chunks without dual-runtime hazard. ```typescript import { init, loadRemote } from '@module-federation/runtime'; // IMMUTABLE FEDERATION CONTRACT: Enforces exact singletons and shared cache parity export const federatedConfig = { name: 'edge_consumer', remotes: [ { name: 'remote_catalog', entry: 'https://cdn.edge.domain/catalog/mf-manifest.json', }, ], shared: { react: { version: '19.0.0', singleton: true, requiredVersion: '^19.0.0' }, 'react-dom': { version: '19.0.0', singleton: true, requiredVersion: '^19.0.0' }, }, } as const; init(federatedConfig); export async function getRemoteCatalogComponent<T = React.ComponentType>() { const module = await loadRemote<T>('remote_catalog/ProductCard'); if (!module) { throw new Error('[Federation Invariant] Failed to resolve remote_catalog/ProductCard deterministically'); } return module; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Rolldown Deterministic Module Chunking & Federated Edge Invariant

Rolldown Deterministic Module Chunking & Federated Edge Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces byte-for-byte reproducible bundle hashes, topological module ordering, and shared-dependency singleton deduplication across federated Vite 6 and Rolldown edge builds. Prevents module identity drift, dual-package hazard at runtime edge nodes, and volatile chunk graph invalidations caused by non-deterministic dynamic chunk allocation. 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: Non-Deterministic Dynamic Chunk Splitting and Platform-Dependent Path Ingestion 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	Non-Deterministic Dynamic Chunk Splitting and Platform-Dependent Path Ingestion	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 normalize all module file paths to POSIX standard before chunk assignment evaluation to eliminate OS-level hashing discrepancies.

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.