Vite 6 Environment API Multi-Runtime SSR Target Isolation

--- description: Vite 6 Environment API Multi-Runtime SSR Target Isolation - Enforces strict isolation of execution runtimes (client, node, edge/workerd) using Vite 6's Environment API. Eliminates polyfill cross-contamination, shared module graph pollution, and global scope leakage across heterogenous SSR compilation targets in a single pipeline. globs: vite.config.ts, vite.config.*.ts, src/entry.server.ts, src/entry.edge.ts, src/entry.client.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-isolation" --- # Vite 6 Environment API Multi-Runtime SSR Target Isolation > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Global Module Graph Leakage and Polyfill Pollution Across Heterogeneous Runtimes ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API standards. You must mandate isolated module graphs, segregated plugin hooks, and separate runtime environments across Client, Node.js, and Edge targets. Prevent legacy multi-config spawning, global polyfill contamination, and environment context leakage. ## Strict Guidelines - Engineers MUST ALWAYS define distinct runtime targets using the top-level `environments` configuration block introduced in Vite 6, rather than spawning parallel legacy Vite build processes. - Engineers MUST configure `resolve.conditions` and `resolve.externalConditions` independently per environment (e.g., `['workerd', 'worker']` for edge targets, `['node']` for Node SSR targets). - Engineers MUST NOT apply global Node.js polyfill plugins (e.g., `rollup-plugin-node-polyfills`) to the root Vite plugin array; polyfills MUST be constrained strictly to the target environment's pipeline. - Plugins MUST utilize Vite 6 environment-aware lifecycle hooks (`applyToEnvironment(env)`, `hotUpdate(ctx)`, `resolveId(id, importer, options)`) rather than mutating global server state or relying on global `ssr` boolean flags. - Code executed in Edge/Workerd environments MUST NEVER reference Node.js built-ins (`fs`, `path`, `process`) unless guarded by explicit environment-conditioned exports or isolated polyfills. - Shared utilities MUST NOT export runtime-specific singletons or mutate global objects (`globalThis`, `window`) to avoid state leakage during multi-environment HMR. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Isolation vs Legacy Monolithic SSR Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Applying polyfill plugins globally and mixing export conditions like 'node' and 'workerd' causes cross-contamination. Edge builds will inherit Node shims or resolve incorrect package exports, leading to runtime failures and inflated bundles. ```typescript import { defineConfig } from 'vite'; import nodePolyfills from 'vite-plugin-node-polyfills'; // ANTI-PATTERN: Monolithic SSR configuration leaking Node polyfills and globals to edge and client export default defineConfig({ plugins: [ nodePolyfills(), // Leaks polyfills globally to client, edge, and node ], build: { ssr: true, // Legacy binary flag: cannot distinguish between Node and Edge runtimes }, resolve: { conditions: ['node', 'workerd'], // Conflicting conditions applied simultaneously }, }); ``` #### Production Standard (Correct) > **Standard**: Leverages the Vite 6 Environment API to partition client, Node SSR, and Edge runtimes into fully segregated module graphs. Explicit conditions prevent polyfill leakage and ensure runtime-specific package resolution. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Isolated execution environments via Vite 6 Environment API export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, resolve: { conditions: ['browser'], }, }, ssr: { build: { outDir: 'dist/server', }, resolve: { conditions: ['node'], external: true, }, }, edge: { build: { outDir: 'dist/edge', }, resolve: { conditions: ['workerd', 'worker'], noExternal: true, // Edge bundles must inline all dependencies to ensure hermetic execution }, }, }, builder: { buildApp: async (builder) => { // Explicit pipeline order prevents module graph pollution await builder.build(builder.environments.client); await builder.build(builder.environments.ssr); await builder.build(builder.environments.edge); }, }, }); ``` ### Environment-Aware Plugin Scoping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relying on the boolean `options.ssr` flag fails in multi-runtime architectures. It injects `node:os` into edge environments (e.g., Cloudflare Workers), triggering runtime boot crashes. ```typescript import type { Plugin } from 'vite'; // ANTI-PATTERN: Plugin blindly assumes SSR means Node.js export function injectTelemetry(): Plugin { return { name: 'telemetry', transform(code, id, options) { if (options?.ssr) { // Injects Node.js specific code into what might be an Edge runtime return `import os from 'node:os';\nconst host = os.hostname();\n${code}`; } return code; }, }; } ``` #### Production Standard (Correct) > **Standard**: Uses Vite 6's `applyToEnvironment` hook to guarantee that Node.js specific code transformations execute strictly within the designated Node SSR environment, shielding the Edge and Client bundles. ```typescript import type { Plugin } from 'vite'; // PRODUCTION INVARIANT: Environment-scoped plugin execution via Vite 6 applyToEnvironment export function injectTelemetry(): Plugin { return { name: 'telemetry', // Vite 6 environment filtering hook applyToEnvironment(environment) { return environment.name === 'ssr'; // Strictly targets the Node.js SSR runtime }, transform(code, id) { return `import os from 'node:os';\nconst host = os.hostname();\n${code}`; }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime SSR Target Isolation

Vite 6 Environment API Multi-Runtime SSR Target Isolation defines an industrial-grade behavioral standard for devops engineering. Enforces strict isolation of execution runtimes (client, node, edge/workerd) using Vite 6's Environment API. Eliminates polyfill cross-contamination, shared module graph pollution, and global scope leakage across heterogenous SSR compilation targets in a single pipeline. 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: Global Module Graph Leakage and Polyfill Pollution Across Heterogeneous 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	Global Module Graph Leakage and Polyfill Pollution Across Heterogeneous 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 define distinct runtime targets using the top-level `environments` configuration block introduced in Vite 6, rather than spawning parallel legacy Vite build processes.

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.