Strict Vite 6 Environment API Multi-Runtime Memory and Process Boundary Guardrail

--- description: Strict Vite 6 Environment API Multi-Runtime Memory and Process Boundary Guardrail - Enforces isolated execution boundaries across Vite 6 Environment API runtimes by decoupling Node.js host servers from edge-worker virtual environments. Prevents cross-realm prototype pollution and non-public environment variable leakage through strict runtime boundary segregation and explicit runner configuration. globs: vite.config.{ts,js,mjs}, src/server/**/*.{ts,js}, src/entry.worker/**/*.{ts,js}, src/entry.server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-worker-sandbox-isolation" --- # Strict Vite 6 Environment API Multi-Runtime Memory and Process Boundary Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing edge worker runtimes within the Node.js root SSR execution context sharing global scope and process.env ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Multi-Runtime Worker Sandbox Pattern. You must ensure that Vite 6 development configurations and SSR runners strictly separate execution contexts for browser, server (Node.js), and edge/worker environments. Reject any configuration that shares module graphs, injects Node.js host globals into edge worker runtimes, or evaluates worker entry points in the host server process without a sandboxed ModuleRunner or isolated worker thread. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments in `vite.config.ts` using the Vite 6 `environments` record, separating `client`, `ssr` (Node.js), and `edge`/`worker` instances. - Engineers MUST configure worker environments with a dedicated `RunnableDevEnvironment` using isolated runners such as worker threads or Miniflare/workerd runtimes rather than executing within the host Node.js event loop. - Engineers MUST NOT access `process.env` directly within modules designated for edge/worker environments; all environment variables MUST be resolved via runtime bindings or sanitized `define` objects scoped strictly to that environment. - Code MUST NEVER share stateful singleton instances or mutate shared prototype chains across runtime boundaries; all communication between the Node.js dev server and worker environments MUST pass over structured clone channels or explicit IPC transport. - Services MUST explicitly declare `resolve.noExternal` for edge runtimes to avoid leaking Node.js CJS module formats and core native module access (e.g., `fs`, `crypto`) into edge sandboxes. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Configuration and Isolated Environment Definition #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defining a monolithic SSR target with 'webworker' evaluates edge code inside the same Node.js execution context as dev server middleware, exposing Node globals, leaking secret environment variables, and allowing cross-realm prototype mutations. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy pattern running edge worker logic inside the host Node SSR context export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, define: { // Leaks entire host process environment into the bundle 'process.env': JSON.stringify(process.env), }, }); ``` #### Production Standard (Correct) > **Standard**: Explicitly declares an isolated 'edge' environment using Vite 6's Environment API. Assigns a dedicated WorkerThreadRunner and hot channel, isolating the global scope and preventing Node host globals and sensitive process.env keys from leaking into the edge runtime. ```typescript import { defineConfig, createServerHotChannel } from 'vite'; import { createRunnableDevEnvironment } from 'vite'; import { WorkerThreadRunner } from 'vite/module-runner'; // PRODUCTION INVARIANT: Vite 6 isolated environment declarations export default defineConfig({ environments: { client: { consumer: 'client', }, ssr: { consumer: 'server', build: { outDir: 'dist/server' }, }, edge: { consumer: 'server', resolve: { conditions: ['worker', 'edge-light', 'browser'], noExternal: true, }, dev: { createEnvironment(name, config) { const hot = createServerHotChannel(); const runner = new WorkerThreadRunner(); return createRunnableDevEnvironment(name, config, { hot, runner, }); }, }, define: { 'import.meta.env.WORKER_REGION': JSON.stringify('us-east-1'), }, }, }, }); ``` ### Module Runner Execution Invariant for Edge Workers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: ssrLoadModule executes modules directly inside the Node.js server realm, bypassing runtime sandboxes, allowing edge code to pollute host Object.prototype and access Node.js built-ins. ```typescript import { ViteDevServer } from 'vite'; // ANTI-PATTERN: Executing edge entrypoint using host Node.js ssrLoadModule export async function handleRequest(server: ViteDevServer, url: string) { const workerEntry = await server.ssrLoadModule('/src/entry.worker.ts'); // workerEntry runs in host Node.js realm; prototype pollution directly impacts dev server return workerEntry.default.fetch(new Request(url)); } ``` #### Production Standard (Correct) > **Standard**: Accesses the dedicated 'edge' environment from server.environments and imports the module using the environment's isolated runner, keeping execution completely separated from the Node.js host process. ```typescript import { ViteDevServer } from 'vite'; // PRODUCTION INVARIANT: Invoking execution via the sandboxed Vite 6 Environment export async function handleRequest(server: ViteDevServer, url: string) { const edgeEnv = server.environments.edge; if (!('runner' in edgeEnv)) { throw new Error('Edge environment is not configured as a RunnableDevEnvironment'); } // Module runs entirely inside the isolated worker thread context const workerEntry = await edgeEnv.runner.import('/src/entry.worker.ts'); const request = new Request(url); return await workerEntry.default.fetch(request, edgeEnv.runner.context); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict Vite 6 Environment API Multi-Runtime Memory and Process Boundary Guardrail

Strict Vite 6 Environment API Multi-Runtime Memory and Process Boundary Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces isolated execution boundaries across Vite 6 Environment API runtimes by decoupling Node.js host servers from edge-worker virtual environments. Prevents cross-realm prototype pollution and non-public environment variable leakage through strict runtime boundary segregation and explicit runner configuration. 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: Executing edge worker runtimes within the Node.js root SSR execution context sharing global scope and process.env 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	Executing edge worker runtimes within the Node.js root SSR execution context sharing global scope and process.env	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 in `vite.config.ts` using the Vite 6 `environments` record, separating `client`, `ssr` (Node.js), and `edge`/`worker` instances.

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.