Vite 6 & Rolldown Module Tree-Shaking and Edge SSR Side-Effect Isolation Standard

--- description: Vite 6 & Rolldown Module Tree-Shaking and Edge SSR Side-Effect Isolation Standard - Mandates absolute module-level side-effect isolation for Vite 6 Rolldown-native edge SSR compilation to guarantee deterministic sub-50ms cold-start execution. Eliminates module-scope object allocations, un-annotated global initializations, and barrel-file side-effect leaks that destabilize tree-shaking boundaries in isolated V8 edge runtimes. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-rolldown-chunk-tree-shaking-isolation-standard" --- # Vite 6 & Rolldown Module Tree-Shaking and Edge SSR Side-Effect Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Eager Module-Scope Instantiation and Leaky Dynamic Imports in Edge SSR Runtimes ## System Constraints You are a Principal Software Architect enforcing Vite 6 Rolldown-native compilation standards for edge SSR applications. Enforce strict module-level purity, immutable chunk boundaries, and total elimination of top-level runtime evaluation to guarantee sub-50ms V8 isolate cold-start latency. ## Strict Guidelines - Engineers MUST ALWAYS isolate top-level module side effects behind lazy factory closures or getter functions to permit Rolldown dead-code elimination. - Engineers MUST NOT instantiate database clients, cryptographic state, analytics SDKs, or DOM-dependent singletons in global module scope. - Code MUST explicitly annotate non-primitive top-level constant evaluations with /* @__PURE__ */ comments when calling pure utility functions. - Vite configuration MUST define explicit Rolldown treeshake options (`moduleSideEffects: 'no-external'`, `annotations: true`) in SSR edge target environments. - Package manifests in internal monorepo dependencies MUST declare explicit granular `sideEffects` globs rather than wildcard booleans. - Components and server handlers NEVER import barrel index files; imports MUST reference explicit, isolated module leaf paths. - Dynamic imports for SSR conditional branches MUST resolve to static specifiers to avoid de-optimizing Rolldown chunk graph boundary splitting. ## Bad vs Good Implementations ### Module-Level SDK Instantiation vs. Lazy Weak-Referenced Factory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Instantiating client connections and cryptographic hashes in module scope executes unconditionally during edge isolate initialization. This causes cold-start latency spikes exceeding 150ms and prevents Rolldown from eliminating unused edge route branches. ```typescript // Top-level evaluation executes immediately upon chunk evaluation in Edge SSR, // forcing Rolldown to retain heavy runtime dependencies in every entry chunk. import { Redis } from '@upstash/redis'; import { createHash } from 'node:crypto'; // Module-scope side effect: forces TCP/HTTP instantiation on cold boot export const redisClient = new Redis({ url: process.env.UPSTASH_REDIS_REST_URL!, token: process.env.UPSTASH_REDIS_REST_TOKEN!, }); // Module-scope mutation and immediate execution export const DEFAULT_CACHE_KEY_PREFIX = createHash('sha256') .update(process.env.APP_DEPLOYMENT_ID || 'local') .digest('hex'); export async function getSession(id: string) { return await redisClient.get(`session:${DEFAULT_CACHE_KEY_PREFIX}:${id}`); } ``` #### Production Standard (Correct) > **Standard**: Defers connection initialization until invocation within the SSR request handler, uses tree-shakeable pure functional closures, and preserves zero module-level execution overhead during chunk load. ```typescript import type { Redis } from '@upstash/redis'; // Pure declaration: no top-level side effects or edge memory allocation let cachedRedis: Redis | null = null; export function getRedisClient(): Redis { if (!cachedRedis) { const { Redis: RedisConstructor } = require('@upstash/redis') as typeof import('@upstash/redis'); cachedRedis = new RedisConstructor({ url: process.env.UPSTASH_REDIS_REST_URL!, token: process.env.UPSTASH_REDIS_REST_TOKEN!, }); } return cachedRedis; } // Rolldown recognizes PURE annotation and drops this call if unused export const getCachePrefix = /* @__PURE__ */ (() => { return (prefix: string, deploymentId?: string): string => `${prefix}:${deploymentId ?? 'local'}`; })(); export async function getSession(id: string): Promise<unknown> { const client = getRedisClient(); const prefix = getCachePrefix('session', process.env.APP_DEPLOYMENT_ID); return await client.get(`${prefix}:${id}`); } ``` ### Vite 6 Rolldown SSR Chunk Isolation Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default Vite SSR configurations without explicit Rolldown tree-shaking definitions treat external module boundaries permissively, inadvertently bundling unused modules into worker initializers. ```typescript import { defineConfig } from 'vite'; export default defineConfig({ build: { ssr: true, rollupOptions: { // Flawed: Default Rollup tree-shaking allows module-level side-effects // to propagate across node_modules boundaries in edge workers external: ['@upstash/redis'], }, }, }); ``` #### Production Standard (Correct) > **Standard**: Configures strict Rolldown tree-shaking semantics with 'no-external' moduleSideEffects and explicit purity heuristics, ensuring dead chunks are dropped before isolate compilation. ```typescript import { defineConfig } from 'vite'; export default defineConfig({ build: { target: 'esnext', ssr: true, rollupOptions: { treeshake: { preset: 'recommended', moduleSideEffects: 'no-external', annotations: true, manualPureFunctions: ['createSlice', 'createSignal', 'z.object'], unknownGlobalSideEffects: false, }, output: { format: 'esm', inlineDynamicImports: false, chunkFileNames: 'chunks/[name]-[hash].js', generatedCode: { preset: 'es2015', symbols: false, }, }, }, }, ssr: { target: 'webworker', noExternal: true, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 & Rolldown Module Tree-Shaking and Edge SSR Side-Effect Isolation Standard

Vite 6 & Rolldown Module Tree-Shaking and Edge SSR Side-Effect Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Mandates absolute module-level side-effect isolation for Vite 6 Rolldown-native edge SSR compilation to guarantee deterministic sub-50ms cold-start execution. Eliminates module-scope object allocations, un-annotated global initializations, and barrel-file side-effect leaks that destabilize tree-shaking boundaries in isolated V8 edge runtimes. 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: Eager Module-Scope Instantiation and Leaky Dynamic Imports in Edge SSR Runtimes 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	Eager Module-Scope Instantiation and Leaky Dynamic Imports in Edge SSR Runtimes	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 isolate top-level module side effects behind lazy factory closures or getter functions to permit Rolldown dead-code elimination.

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.