Vite 6 Environment API Segmentation and Zero-Leak Module Isolation

--- description: Vite 6 Environment API Segmentation and Zero-Leak Module Isolation - Enforces strict boundary segmentation across browser, Node.js, and edge runtimes using the Vite 6 Environment API. Guarantees zero module leak, deterministic polyfill elimination, and isolated module graphs during unified client, SSR, and edge builds. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-boundary-segmentation-standard" --- # Vite 6 Environment API Segmentation and Zero-Leak Module Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Multi-Target Configs Causing Node Polyfill Leakage and Runtime Boundary Cross-Contamination ## System Constraints You are a Principal Software Architect enforcing rigorous Vite 6 Environment API standards. You mandate explicit environment boundary segmentation (client, ssr, edge, workerd) within vite.config.ts. You prohibit global polyfills, ambient runtime sniffing, shared optimizeDeps matrices, and unconstrained export conditions that risk node built-in bleed into client or edge bundles. ## Strict Guidelines - Engineers MUST ALWAYS declare isolated execution targets via top-level 'environments' (e.g., client, ssr, edge) instead of legacy monolithic root-level plugins and build options. - Engineers MUST configure discrete 'resolve.conditions' per environment ('browser' for client, 'node' for SSR, 'worker' or 'workerd' for edge runtimes). - Engineers MUST NOT inject Node.js polyfill plugins (e.g., rollup-plugin-node-polyfills) into root-level or client environment plugins. - Engineers MUST ALWAYS externalize runtime-specific built-ins via 'build.rollupOptions.external' or 'resolve.external' inside the specific environment block. - Components NEVER determine environment capabilities via ambient global inspection (e.g., 'typeof window !== "undefined"') for module import branching; engineers MUST use package.json subpath imports ('#runtime') or explicit environment-scoped entry points. - Code MUST strictly segregate client-only and server-only stateful modules to avoid cross-request memory leaks in persistent SSR/Edge daemon instances. - Plugins targeting specific lifecycle phases MUST check 'this.environment.name' rather than assuming execution in a client browser graph. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Pollutes the entire bundle with synthetic Node.js polyfills, overrides native browser crypto/buffer APIs, and prevents fine-grained optimization across divergent runtimes (client vs. SSR vs. Edge). ```typescript import { defineConfig } from 'vite'; import nodePolyfills from 'vite-plugin-node-stdlib-browser'; // ANTI-PATTERN: Monolithic configuration with global polyfills and shared build matrix export default defineConfig({ plugins: [nodePolyfills()], resolve: { alias: { crypto: 'crypto-browserify', buffer: 'buffer/' } }, build: { ssr: false, rollupOptions: { output: { manualChunks: { vendor: ['react', 'react-dom'] } } } } }); ``` #### Production Standard (Correct) > **Standard**: Defines discrete execution pipelines using the Vite 6 Environment API. Runtimes get deterministic export condition matching, targeted externals, zero synthetic polyfill leaks, and distinct output destinations. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Isolated Vite 6 Environment API boundaries export default defineConfig({ environments: { client: { resolve: { conditions: ['browser', 'module', 'import'], noExternal: true }, build: { outDir: 'dist/client', minify: 'esbuild', rollupOptions: { input: '/src/entry-client.tsx' } } }, ssr: { resolve: { conditions: ['node', 'module', 'import'], external: [/^node:/, 'express'] }, build: { outDir: 'dist/server', ssr: true, rollupOptions: { input: '/src/entry-server.tsx' } } }, edge: { resolve: { conditions: ['workerd', 'worker', 'module', 'import'], external: [/^cloudflare:/] }, build: { outDir: 'dist/edge', rollupOptions: { input: '/src/entry-edge.ts' } } } } }); ``` ### Environment Guarded Custom Vite Plugin #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transforms code indiscriminately across all environments, exposing backend secrets to the client compilation pipeline. ```typescript import type { Plugin } from 'vite'; // ANTI-PATTERN: Plugin blindly assumes client context and transforms all environments export function transformSecretPlugin(): Plugin { return { name: 'transform-secret', transform(code, id) { if (code.includes('SECRET_KEY')) { return code.replace(/SECRET_KEY/g, JSON.stringify(process.env.SECRET_KEY)); } return null; } }; } ``` #### Production Standard (Correct) > **Standard**: Uses Vite 6 'applyToEnvironment' hook and 'this.environment.name' runtime checks to eliminate secret exposure and isolate side effects to appropriate server/edge boundaries. ```typescript import type { Plugin } from 'vite'; // PRODUCTION INVARIANT: Environment-scoped transformation guard export function transformSecretPlugin(): Plugin { return { name: 'transform-secret', applyToEnvironment(environment) { // Restrict execution exclusively to SSR and edge environments return environment.name === 'ssr' || environment.name === 'edge'; }, transform(code, id) { if (this.environment.name === 'client') { return null; } if (code.includes('SECRET_KEY')) { return { code: code.replace(/SECRET_KEY/g, JSON.stringify(process.env.SECRET_KEY ?? '')), map: null }; } return null; } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Segmentation and Zero-Leak Module Isolation

Vite 6 Environment API Segmentation and Zero-Leak Module Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary segmentation across browser, Node.js, and edge runtimes using the Vite 6 Environment API. Guarantees zero module leak, deterministic polyfill elimination, and isolated module graphs during unified client, SSR, and edge builds. 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: Monolithic Multi-Target Configs Causing Node Polyfill Leakage and Runtime Boundary Cross-Contamination 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	Monolithic Multi-Target Configs Causing Node Polyfill Leakage and Runtime Boundary Cross-Contamination	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 isolated execution targets via top-level 'environments' (e.g., client, ssr, edge) instead of legacy monolithic root-level plugins and build options.

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.