Vite 6 Environment API Workerd-SSR Context Boundary Enforcement

--- description: Vite 6 Environment API Workerd-SSR Context Boundary Enforcement - Vite 6's Environment API enables isolated multi-runtime pipelines (e.g., client, edge/workerd, and node). Engineers must enforce strict compile-time module resolution barriers, condition fencing, and bundle virtualization to prevent Node.js native primitives, un-sandboxed global access, and private server secrets from leaking into Cloudflare Workerd edge worker bundles. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-workerd-ssr-context-boundary" --- # Vite 6 Environment API Workerd-SSR Context Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Node.js Builtins and Un-sandboxed Host Globals into Vite 6 Workerd SSR Environments ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API Workerd-SSR Context Boundaries. You must mandate strict physical and logical boundaries between Node.js execution environments, client runtimes, and Cloudflare Workerd edge targets. Reject any code path that leaks Node.js builtins (fs, path, child_process), direct process.env access, or Node-dependent packages into the workerd environment configuration. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct `environments` blocks in Vite 6 (`client`, `workerd`/`ssr`) with runtime-specific `resolve.conditions` containing `['workerd', 'worker']` to avoid Node fallback resolutions. - Engineers MUST NOT reference un-polyfilled Node.js native modules (`node:fs`, `node:child_process`, `node:os`) inside modules evaluated by the Workerd SSR environment. - Engineers MUST NEVER access raw `process.env` in edge-targeted SSR handlers; environment variables and bindings MUST be accessed strictly via Cloudflare's runtime context or Vite's `import.meta.env` with strict prefixing. - Code MUST isolate server-only secrets into explicit server entry boundaries using Vite's `noExternal` in the Workerd environment configuration to ensure explicit bundling or externalization of compatible web-standard libraries. - Components and shared isomorphic libraries MUST NEVER import backend-specific SDKs; use dependency injection or service bindings at the entry-point boundary. - Build scripts MUST validate that workerd outputs do not contain dynamic requires or unresolved references to Node platform globals prior to deployment. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Configuration for Workerd SSR #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy generic SSR configs assume a Node.js target by default. In Vite 6, omitting the explicit 'workerd' environment definition causes resolution plugins to use Node export conditions, allowing native Node builtins and incompatible packages to bundle into the edge target. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy SSR configuration treating SSR as generic Node environment export default defineConfig({ ssr: { noExternal: true, }, build: { ssr: 'src/entry-server.ts', }, }); ``` #### Production Standard (Correct) > **Standard**: Declares an explicit `ssr` environment using Vite 6's Environment API with `workerd` and `worker` resolve conditions. Prevents Node.js module resolution branches and safely marks Cloudflare runtime primitives as external. ```typescript import { defineConfig } from 'vite'; // PRODUCTION FIX: Explicit Vite 6 Environment API configuration with workerd condition fencing export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, }, ssr: { resolve: { conditions: ['workerd', 'worker', 'browser'], externalConditions: ['workerd', 'worker'], noExternal: true, }, build: { target: 'esnext', outDir: 'dist/server', ssr: 'src/entry-server.ts', rollupOptions: { external: ['cloudflare:workers'], }, }, }, }, }); ``` ### SSR Server Entrypoint Runtime Boundary Separation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly imports `node:fs` and `node:path` and references `process.env`. Workerd lacks native Node filesystem access without specific polyfills, and process.env is undefined or insecure in Workers runtime contexts. ```typescript import fs from 'node:fs'; import path from 'node:path'; // ANTI-PATTERN: Relying on Node built-ins and process.env inside an edge SSR entrypoint export default { async fetch(request: Request) { const template = fs.readFileSync(path.resolve('./index.html'), 'utf-8'); const dbKey = process.env.DATABASE_PRIVATE_KEY; return new Response(template.replace('{{KEY}}', dbKey || '')); } }; ``` #### Production Standard (Correct) > **Standard**: Employs Vite's static asset import (`?raw`) to avoid runtime filesystem read calls, uses type-safe edge parameters (`env`) instead of Node globals (`process.env`), and keeps the bundle 100% compliant with Workerd runtime guarantees. ```typescript /// <reference types="@cloudflare/workers-types" /> import template from './index.html?raw'; interface Env { DATABASE_PRIVATE_KEY: string; } // PRODUCTION FIX: Edge-native static asset handling and context-bound environment variables export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> { const dbKey = env.DATABASE_PRIVATE_KEY; const html = template.replace('', `<script>window.__READY__ = true;</script>`); return new Response(html, { headers: { 'content-type': 'text/html;charset=utf-8' }, }); } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Workerd-SSR Context Boundary Enforcement

Vite 6 Environment API Workerd-SSR Context Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Vite 6's Environment API enables isolated multi-runtime pipelines (e.g., client, edge/workerd, and node). Engineers must enforce strict compile-time module resolution barriers, condition fencing, and bundle virtualization to prevent Node.js native primitives, un-sandboxed global access, and private server secrets from leaking into Cloudflare Workerd edge worker bundles. 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: Leaking Node.js Builtins and Un-sandboxed Host Globals into Vite 6 Workerd SSR 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	Leaking Node.js Builtins and Un-sandboxed Host Globals into Vite 6 Workerd SSR 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` blocks in Vite 6 (`client`, `workerd`/`ssr`) with runtime-specific `resolve.conditions` containing `['workerd', 'worker']` to avoid Node fallback resolutions.

Engineers MUST ALWAYS configure distinct `environments` blocks in Vite 6 (`client`, `workerd`/`ssr`) with runtime-specific `resolve.conditions` containing `['workerd', 'worker']` to avoid Node fallback resolutions.

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.