Vite 6 Environment API Worker-Thread Sandbox Isolation and Lifecycle Management

--- description: Vite 6 Environment API Worker-Thread Sandbox Isolation and Lifecycle Management - Enforces strict process and worker-thread isolation across heterogeneous runtime targets (Client, Node SSR, Edge/Workerd) utilizing the Vite 6 Environment API. Prevents module graph cross-contamination, polyfill pollution of global scopes, and heap accumulation by mandating explicit environment runners, isolated resolution conditions, and deterministic lifecycle teardowns. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-sandbox-worker-isolation" --- # Vite 6 Environment API Worker-Thread Sandbox Isolation and Lifecycle Management > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Dev Server Runtime Sharing Module Graphs and Ambient State Across SSR and Edge Targets ## System Constraints You are a Principal Software Architect enforcing strict runtime and module-graph boundary integrity using the Vite 6 Environment API. You must reject legacy SSR dev server patterns that execute multiple target environments (Node, Edge, Browser) within the primary Vite daemon thread. Enforce isolated worker runtimes, separate environment transform graphs, strict resolution conditions, and deterministic memory reclamation. ## Strict Guidelines - Engineers MUST ALWAYS declare disparate runtime targets as independent environments under Vite 6 `environments` configuration rather than running untyped runtime flags. - Engineers MUST NOT execute SSR or Edge module execution within the root Node.js process hosting the Vite compilation server; all execution MUST use isolated Worker runners. - Code SHOULD enforce distinct `resolve.conditions` per environment (e.g., `['edge-light', 'worker']` for edge targets vs `['node']` for standard SSR) to eliminate dual-package hazard. - Services MUST register deterministic lifecycle teardown hooks invoking `environment.close()` and worker termination to prevent uncollectible graph nodes across HMR cycles. - Components and shared libraries NEVER mutate `globalThis` or rely on un-namespaced polyfills that can leak across worker boundaries or pollute the host daemon heap. ## Bad vs Good Implementations ### Legacy Unsafe Monolithic SSR vs Vite 6 Worker-Isolated Multi-Environment Architecture #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing `server.ssrLoadModule` runs arbitrary server/edge code in the main Vite process. Polyfills applied to `globalThis` cross-contaminate the client bundler and other environments. Module cache accumulation occurs without teardown hooks, creating uncollectible memory leaks during HMR. ```typescript import { defineConfig } from 'vite'; import type { ViteDevServer } from 'vite'; // Anti-pattern: Monolithic runner sharing Node runtime with Edge and Client export default defineConfig({ ssr: { noExternal: true, }, plugins: [ { name: 'unsafe-ssr-runner', configureServer(server: ViteDevServer) { // Pollutes root process global scope with edge polyfills (globalThis as unknown as { EdgeRuntime: string }).EdgeRuntime = 'edge-fake'; return () => { server.middlewares.use(async (req, res) => { // Legacy ssrLoadModule executes inside Vite host process // Causing heap leaks, module graph pollution, and cross-runtime crashes const entry = await server.ssrLoadModule('/src/entry-edge.ts'); const html = await entry.render(req.url); res.end(html); }); }; }, }, ], }); ``` #### Production Standard (Correct) > **Standard**: Defines isolated Vite 6 environments with tailored `resolve.conditions`. Offloads the Edge module execution graph into a discrete `Worker` thread via `createRunnableDevEnvironment`. Enforces automatic resource and heap reclamation in the `lifecycle.close` hook when the environment is disposed or rebuilt. ```typescript import { defineConfig } from 'vite'; import { createRunnableDevEnvironment } from 'vite'; import { Worker } from 'node:worker_threads'; export default defineConfig({ environments: { client: { build: { outDir: 'dist/client' }, }, edge: { resolve: { conditions: ['edge-light', 'worker', 'import'], noExternal: true, }, dev: { createEnvironment(name, config) { // Strict Worker-Thread Isolation boundary const worker = new Worker(new URL('./edge-runner-worker.ts', import.meta.url), { workerData: { environmentName: name }, }); return createRunnableDevEnvironment(name, config, { runner: { async run(entryPoint, options) { return new Promise((resolve, reject) => { worker.postMessage({ type: 'EXECUTE', entryPoint, options }); worker.once('message', (msg) => (msg.error ? reject(msg.error) : resolve(msg.result))); }); }, }, lifecycle: { async close() { // Deterministic memory reclamation await worker.terminate(); }, }, }); }, }, }, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Worker-Thread Sandbox Isolation and Lifecycle Management

Vite 6 Environment API Worker-Thread Sandbox Isolation and Lifecycle Management defines an industrial-grade behavioral standard for frontend engineering. Enforces strict process and worker-thread isolation across heterogeneous runtime targets (Client, Node SSR, Edge/Workerd) utilizing the Vite 6 Environment API. Prevents module graph cross-contamination, polyfill pollution of global scopes, and heap accumulation by mandating explicit environment runners, isolated resolution conditions, and deterministic lifecycle teardowns. 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 Dev Server Runtime Sharing Module Graphs and Ambient State Across SSR and Edge Targets 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 Dev Server Runtime Sharing Module Graphs and Ambient State Across SSR and Edge Targets	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 disparate runtime targets as independent environments under Vite 6 `environments` configuration rather than running untyped runtime flags.

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.