Vite 6 Environment API Runtime Sandboxing Standard

--- description: Vite 6 Environment API Runtime Sandboxing Standard - Vite 6 introduces the Environment API to provide distinct, sandboxed module graphs and execution contexts for client, SSR, and custom runtime targets (e.g., edge workers). This standard mandates explicit per-environment configuration, boundary fencing via environment-aware plugin hooks, and the deprecation of legacy server-side execution APIs to eliminate cross-environment credential leaks and compilation contamination. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-runtime-sandboxing-standard" --- # Vite 6 Environment API Runtime Sandboxing Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Server Secrets and Private Backend Modules into Client Artifacts via Legacy Monolithic Configuration and Unscoped Vite Plugins ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Runtime Sandboxing Standard. You must ensure that client, SSR, and edge environments maintain completely isolated module graphs, dependency trees, and runtime defines. Mandate that Vite configurations migrate from legacy monolithic properties to the `environments` option, enforce compilation-level isolation using `this.environment.name` in plugin hooks, and reject any import or injection of privileged backend secrets into the client environment graph. ## Strict Guidelines - Engineers MUST ALWAYS configure isolated module execution contexts using Vite 6's top-level `environments` configuration block (defining distinct `client`, `ssr`, and optional `edge`/`workerd` environments) instead of shared global settings. - Engineers MUST NOT declare global `define` objects at the Vite root configuration that inline un-prefixed server-side environment variables or privileged API keys across all build targets. - Custom Vite plugins MUST query `this.environment.name` in resolution and transformation hooks (`resolveId`, `load`, `transform`) to strictly assert whether an imported module is permitted in the active compilation runtime. - Plugins MUST throw a fatal build error if a module marked as server-only (matching convention `*.server.ts` or imports from `#server/*`) resolves within the `client` environment graph. - Runtime execution in development MUST utilize environment runners (e.g., `server.environments.ssr.runner.import()`) rather than the deprecated `viteDevServer.ssrLoadModule()` root interface. - Components and frontend utilities NEVER directly import server infrastructure, database ORM clients, or raw node-native modules unless actively compiling under an explicit `ssr` or non-client environment. ## Bad vs Good Implementations ### Vite 6 Environment Configuration and Guardrail Plugin #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using monolithic root-level configuration with global `define` variables risks inlining high-privilege server credentials directly into client bundles. The plugin fails to query environment context, allowing server-only modules to cross the client boundary without throwing compilation errors. ```typescript // vite.config.ts (Vite 5 monolithic anti-pattern prone to secret leaks) import { defineConfig } from 'vite'; export default defineConfig({ // CRITICAL: Global define inlines server secrets directly into client bundle define: { 'process.env.DATABASE_URL': JSON.stringify(process.env.DATABASE_URL), 'process.env.STRIPE_SECRET_KEY': JSON.stringify(process.env.STRIPE_SECRET_KEY), }, // Deprecated global SSR configuration lacks module graph isolation ssr: { noExternal: ['@my-company/shared-sdk'], }, plugins: [ { name: 'legacy-server-guard', // Plugin has no runtime awareness; evaluates client and SSR indiscriminately resolveId(id) { if (id.includes('.server.')) { return null; // Silent pass-through allows client to bundle server files } }, }, ], }); ``` #### Production Standard (Correct) > **Standard**: Adopts the Vite 6 Environment API to isolate client and SSR configurations cleanly. Secret keys are partitioned strictly to the `ssr` environment. The custom plugin inspects `this.environment.name` and halts compilation with a fatal error if server-only modules are referenced within the client environment graph. ```typescript // vite.config.ts (Vite 6 Environment API sandboxed standard) import { defineConfig, Plugin } from 'vite'; function enforceServerModuleBoundary(): Plugin { return { name: 'vite-6-server-module-boundary', resolveId(id, importer) { const isServerOnly = /\.server(\.[cm]?[jt]sx?)?$/.test(id) || id.startsWith('#server/'); // Enforce runtime sandboxing via Environment API if (this.environment.name === 'client' && isServerOnly) { this.error( `Security Boundary Violation: Server-only module "${id}" cannot be imported into client environment from "${importer ?? 'unknown'}".` ); } return null; }, }; } export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', sourcemap: true, }, define: { // Only expose strictly validated public variables 'import.meta.env.VITE_PUBLIC_API_URL': JSON.stringify(process.env.VITE_PUBLIC_API_URL), }, resolve: { conditions: ['browser', 'module'], }, }, ssr: { build: { outDir: 'dist/server', ssr: true, }, define: { // Privileged environment variables isolated strictly to SSR sandbox 'process.env.DATABASE_URL': JSON.stringify(process.env.DATABASE_URL), 'process.env.STRIPE_SECRET_KEY': JSON.stringify(process.env.STRIPE_SECRET_KEY), }, resolve: { conditions: ['node', 'module'], }, }, }, plugins: [enforceServerModuleBoundary()], }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Runtime Sandboxing Standard

Vite 6 Environment API Runtime Sandboxing Standard defines an industrial-grade behavioral standard for frontend engineering. Vite 6 introduces the Environment API to provide distinct, sandboxed module graphs and execution contexts for client, SSR, and custom runtime targets (e.g., edge workers). This standard mandates explicit per-environment configuration, boundary fencing via environment-aware plugin hooks, and the deprecation of legacy server-side execution APIs to eliminate cross-environment credential leaks and compilation contamination. 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 Server Secrets and Private Backend Modules into Client Artifacts via Legacy Monolithic Configuration and Unscoped Vite Plugins 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 Server Secrets and Private Backend Modules into Client Artifacts via Legacy Monolithic Configuration and Unscoped Vite Plugins	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 isolated module execution contexts using Vite 6's top-level `environments` configuration block (defining distinct `client`, `ssr`, and optional `edge`/`workerd` environments) instead of shared global settings.

Engineers MUST ALWAYS configure isolated module execution contexts using Vite 6's top-level `environments` configuration block (defining distinct `client`, `ssr`, and optional `edge`/`workerd` environments) instead of shared global settings.

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.