Strict Module & Environment Isolation via Vite 6 Environment API

--- description: Strict Module & Environment Isolation via Vite 6 Environment API - Enforces complete module graph and execution environment segregation across client, edge (workerd), and Node.js runtimes using the Vite 6 Environment API. Prevents cross-runtime module leakage, unconditioned Node.js built-ins in edge/client bundles, and monolithic plugin side-effects across heterogeneous runtime boundaries. globs: vite.config.ts, vite.config.*.ts, src/entry.server.ts, src/entry.client.ts, src/entry.edge.ts, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-runtime-decoupling-vite-6-environme-769" --- # Strict Module & Environment Isolation via Vite 6 Environment API > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Pollinating Module Graphs and Leaking Server Runables into Heterogeneous Vite Environments ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API standards. Vite 6 deprecates monolithic `ssrLoadModule` in favor of explicit per-environment module graphs (client, ssr, edge). You must strictly prevent cross-environment pollution, ensure environment-specific resolve and externalization conditions, and enforce decoupled plugin hooks targeting `this.environment`. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments using `environments.<name>` in Vite 6, setting explicitly scoped `resolve.conditions` and `consumer` properties (e.g., 'client', 'server'). - Engineers MUST NEVER invoke deprecated monolithic runtime methods like `server.ssrLoadModule()` or `server.ssrFixStacktrace()`; use `server.environments[name].runner.import()` instead. - Vite plugins MUST inspect `this.environment.name` inside lifecycle hooks (`resolveId`, `load`, `transform`) when altering resolutions or injecting code intended for only one target runtime. - Code targeting edge environments (e.g., Cloudflare Workers / workerd) MUST NOT import Node.js native built-ins (such as 'node:fs' or 'node:child_process') unless polyfilled or supported under explicit edge runtime flags. - Engineers MUST configure explicit `external` and `noExternal` bundling rules uniquely per environment within `environments.<name>.resolve.external` to avoid shipping server packages to the client graph. - HMR boundaries MUST be isolated per environment; client module changes MUST NOT invalidate or crash the headless edge or Node server runner instances. ## Bad vs Good Implementations ### Vite 6 Decoupled Environment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring SSR via monolithic top-level `ssr` settings forces edge and Node runtimes to share condition paths, risking cross-contamination of globals, leaking Node APIs into client graphs, and preventing multi-environment orchestration. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic SSR and Client shared config in Vite 5 style export default defineConfig({ build: { ssr: true, }, ssr: { noExternal: ['lodash-es'], target: 'node', }, resolve: { // Shared conditions leak Node-specific logic into client or edge conditions: ['node', 'import', 'module'], }, }); ``` #### Production Standard (Correct) > **Standard**: Defines isolated environment boundaries with explicit export conditions and externalization schemes for browser, Node.js, and Cloudflare workerd runtimes. ```typescript import { defineConfig } from 'vite'; import { createRunnableDevEnvironment } from 'vite'; // PRODUCTION INVARIANT: Vite 6 Environment API with isolated runtime topologies export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, resolve: { conditions: ['browser', 'import', 'module'], }, }, ssr: { build: { outDir: 'dist/server', }, resolve: { conditions: ['node', 'import', 'module'], external: ['node:*'], }, }, edge: { build: { outDir: 'dist/edge', }, resolve: { conditions: ['workerd', 'worker', 'browser'], noExternal: true, }, }, }, }); ``` ### Runtime Runner Execution and Environment-Aware Plugin Hook #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses the deprecated Vite 5 `server.ssrLoadModule()` API and applies runtime transforms indiscriminately across all environments, breaking the client and edge module graphs. ```typescript import type { Plugin, ViteDevServer } from 'vite'; export function brokenServerRunnerPlugin(): Plugin { return { name: 'broken-server-runner', configureServer(server: ViteDevServer) { server.middlewares.use(async (req, res, next) => { // ANTI-PATTERN: Using deprecated ssrLoadModule from monolithic server const entry = await server.ssrLoadModule('/src/entry.server.ts'); entry.render(req, res); }); }, transform(code, id) { // ANTI-PATTERN: Blindly injecting Node globals into all environments return `import process from 'node:process';\n${code}`; } }; } ``` #### Production Standard (Correct) > **Standard**: Safely isolates server evaluation via `server.environments[name].runner.import` and gates code transformations strictly on `this.environment.name`. ```typescript import type { Plugin, ViteDevServer } from 'vite'; export function decoupledEnvironmentPlugin(): Plugin { return { name: 'decoupled-environment-plugin', configureServer(server: ViteDevServer) { server.middlewares.use(async (req, res, next) => { const ssrEnv = server.environments.ssr; if (!ssrEnv) { return next(new Error('SSR Environment is not initialized')); } // PRODUCTION INVARIANT: Use Environment Runner to evaluate modules per environment const entry = await ssrEnv.runner.import('/src/entry.server.ts'); entry.render(req, res); }); }, transform(code, id) { // PRODUCTION INVARIANT: Query execution context per environment if (this.environment.name === 'ssr') { return { code: `import process from 'node:process';\n${code}`, map: null, }; } return null; } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict Module & Environment Isolation via Vite 6 Environment API

Strict Module & Environment Isolation via Vite 6 Environment API defines an industrial-grade behavioral standard for frontend engineering. Enforces complete module graph and execution environment segregation across client, edge (workerd), and Node.js runtimes using the Vite 6 Environment API. Prevents cross-runtime module leakage, unconditioned Node.js built-ins in edge/client bundles, and monolithic plugin side-effects across heterogeneous runtime boundaries. 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: Cross-Pollinating Module Graphs and Leaking Server Runables into Heterogeneous Vite Environments 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	Cross-Pollinating Module Graphs and Leaking Server Runables into Heterogeneous Vite Environments	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 distinct environments using `environments.<name>` in Vite 6, setting explicitly scoped `resolve.conditions` and `consumer` properties (e.g., 'client', 'server').

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.