Vite 6 Transitive Modulepreload Pruning for Dynamic Route Manifests

--- description: Vite 6 Transitive Modulepreload Pruning for Dynamic Route Manifests - Mandates explicit pruning of transitive modulepreload dependencies using Vite 6's build.modulePreload.resolveDependencies API. Prevents browser network saturation and main-thread evaluation waterfalls caused by default unconstrained ESM preload graph generation in complex code-split architectures. globs: vite.config.ts, vite.config.*.ts, src/router/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-preload-dependency-manifest-pruning" --- # Vite 6 Transitive Modulepreload Pruning for Dynamic Route Manifests > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unconstrained Dynamic Route Preloading Causing Transitive Modulepreload Network Flooding ## System Constraints You are a Principal Software Architect enforcing Vite 6 Preload Dependency Manifest Pruning. Mandate strict filtering of transitive dependencies in `build.modulePreload.resolveDependencies` to eliminate synthetic network waterfalls and main-thread execution contention caused by unrestrained modulepreload link generation. ## Strict Guidelines - Engineers MUST ALWAYS configure `build.modulePreload.resolveDependencies` in `vite.config.ts` to explicitly prune deep transitive dependencies from dynamic route chunks. - Engineers MUST NOT allow default `build.modulePreload: true` to generate unpruned preload manifests for asynchronous dynamic imports in production builds. - Code SHOULD restrict `modulepreload` links strictly to direct route entries and high-priority critical CSS or shared runtime cores, stripping heavy third-party vendor chunks until actual route navigation. - Services MUST validate that the modulepreload list for any single dynamic entry chunk does not exceed a defined threshold (e.g., max 3-5 critical direct chunks). - Components NEVER trigger secondary asset preloads imperatively without checking if modern manifest-driven pruning already handles the chunk boundary. ## Bad vs Good Implementations ### Vite 6 Modulepreload Dependency Pruning Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defaulting `modulePreload` to true instructs Vite to crawl the complete module graph for every dynamic import, injecting modulepreload links for every transitive dependency, creating severe network resource contention and degrading Core Web Vitals (TBT/LCP). ```typescript import { defineConfig } from 'vite'; export default defineConfig({ build: { // ANTI-PATTERN: Default modulepreload generates preloads for all transitive dependencies, // causing browser queue congestion and 100+ concurrent chunk evaluations on route boundaries. modulePreload: true, }, }); ``` #### Production Standard (Correct) > **Standard**: Configuring `resolveDependencies` filters out non-critical transitive and heavy third-party vendor chunks from dynamically imported entry points, preventing synthetic download cascades and main-thread evaluation storms while preserving critical path performance. ```typescript import { defineConfig } from 'vite'; export default defineConfig({ build: { modulePreload: { resolveDependencies(filename, deps, { hostId, hostType }) { // Invariant: Allow default resolution only for the initial HTML entry point if (hostType === 'html') { return deps; } // Invariant: Prune deep transitive vendor chunks from dynamic route preloads // Only preload critical direct chunks and explicitly whitelisted shared runtime tokens return deps.filter((dep) => { const isNonCriticalVendor = dep.includes('vendor-') && !dep.includes('vendor-core'); const isHeavyLibrary = dep.includes('chart') || dep.includes('monaco') || dep.includes('pdf'); return !isNonCriticalVendor && !isHeavyLibrary; }); }, }, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Transitive Modulepreload Pruning for Dynamic Route Manifests

Vite 6 Transitive Modulepreload Pruning for Dynamic Route Manifests defines an industrial-grade behavioral standard for frontend engineering. Mandates explicit pruning of transitive modulepreload dependencies using Vite 6's build.modulePreload.resolveDependencies API. Prevents browser network saturation and main-thread evaluation waterfalls caused by default unconstrained ESM preload graph generation in complex code-split architectures. 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: Unconstrained Dynamic Route Preloading Causing Transitive Modulepreload Network Flooding 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	Unconstrained Dynamic Route Preloading Causing Transitive Modulepreload Network Flooding	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 configure `build.modulePreload.resolveDependencies` in `vite.config.ts` to explicitly prune deep transitive dependencies from dynamic route chunks.

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.