Vite 6 Rolldown Environment-Scoped Module Sharding Standard

--- description: Vite 6 Rolldown Environment-Scoped Module Sharding Standard - Enforces strict compile-time runtime isolation between client, server, and worker graphs under the Vite 6 Environment API and Rolldown bundler. Prohibits cross-environment symbol bleed, insecure conditional imports relying on runtime presence checks, and shared barrel exports that leak server-only secrets or database primitives into browser manifests. Mandates compile-time condition sharding, environment module manifests, and strict virtual boundary checks. globs: vite.config.ts, src/**/*.{ts,tsx,js,jsx}, package.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-rolldown-environment-sharding-standard" --- # Vite 6 Rolldown Environment-Scoped Module Sharding Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Server Credentials and Secrets via Unisolated Runtime-Guarded Barrel Imports Across Vite 6 Environments ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Rolldown Environment-Scoped Module Sharding Standard. You must mandate compile-time isolation between distinct Vite 6 execution environments (e.g., 'client', 'ssr', 'edge') using Vite 6 Environment APIs and Rolldown sharding directives. You will reject code that relies on fragile runtime guards (e.g., typeof window !== 'undefined') for secret isolation and enforce strict environment subpaths, package exports conditions, and build-time poison checks. ## Strict Guidelines - Engineers MUST ALWAYS configure explicit target environments (client, ssr, edge) in `vite.config.ts` using the Vite 6 `environments` block instead of relying on legacy single-graph conditional builds. - Engineers MUST NOT rely on runtime checks like `typeof window === 'undefined'` or `process.env.SSR` to mask server-only modules, sensitive configurations, or database connections in files reachable by the client graph. - Code SHOULD enforce compile-time poison pill assertions by importing `server-only` in server-only logic, causing Rolldown/Vite to fail the build immediately if bundled in client environments. - Services MUST define distinct module export maps or subpath imports (`#client`, `#server`) using package.json conditional imports or Rolldown alias conditions to guarantee physical bundle separation. - Components NEVER import database clients, ORM schemas, cloud SDKs, or raw API secrets directly into shared component trees, even if the execution is supposedly guarded by lifecycle hooks. ## Bad vs Good Implementations ### Client-Server Code Path Sharding via Vite 6 Environment API and Poison Module #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using runtime `typeof window` checks within the same module causes Rolldown to include the entire dependency tree (including `db` and credentials) in client chunks. Tree-shaking is non-deterministic for complex object graphs, causing server credentials and DB connection strings to leak into client assets. ```typescript // vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ build: { ssr: true, }, }); // src/modules/auth.ts import { db } from './db'; // Direct server DB connection export function getSession(token: string) { // DANGEROUS: Runtime guard does not prevent Rolldown from bundling db code/secrets into client output if (typeof window === 'undefined') { return db.query('SELECT * FROM sessions WHERE token = ?', [token]); } return fetch(`/api/session?token=${encodeURIComponent(token)}`); } ``` #### Production Standard (Correct) > **Standard**: Leverages the Vite 6 `environments` API with explicit resolve conditions (`browser` vs `node`/`server`). The server-specific module includes `server-only` which triggers an immediate compile-time build failure if resolved in the client environment graph, guaranteeing zero secret leakage. ```typescript // vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', rollupOptions: { input: 'src/entry-client.ts', }, }, resolve: { conditions: ['browser'], }, }, ssr: { build: { outDir: 'dist/server', rollupOptions: { input: 'src/entry-server.ts', }, }, resolve: { conditions: ['node', 'server'], }, }, }, }); // src/server/auth.server.ts import 'server-only'; // Hard build-time failure if imported into client environment import { db } from './db'; export async function getSessionServer(token: string) { return db.query('SELECT * FROM sessions WHERE token = ?', [token]); } // src/client/auth.client.ts export async function getSessionClient(token: string) { const res = await fetch(`/api/session?token=${encodeURIComponent(token)}`); return res.json(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Rolldown Environment-Scoped Module Sharding Standard

Vite 6 Rolldown Environment-Scoped Module Sharding Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict compile-time runtime isolation between client, server, and worker graphs under the Vite 6 Environment API and Rolldown bundler. Prohibits cross-environment symbol bleed, insecure conditional imports relying on runtime presence checks, and shared barrel exports that leak server-only secrets or database primitives into browser manifests. Mandates compile-time condition sharding, environment module manifests, and strict virtual boundary checks. 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 Credentials and Secrets via Unisolated Runtime-Guarded Barrel Imports Across Vite 6 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 Server Credentials and Secrets via Unisolated Runtime-Guarded Barrel Imports Across Vite 6 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 explicit target environments (client, ssr, edge) in `vite.config.ts` using the Vite 6 `environments` block instead of relying on legacy single-graph conditional builds.

Engineers MUST ALWAYS configure explicit target environments (client, ssr, edge) in `vite.config.ts` using the Vite 6 `environments` block instead of relying on legacy single-graph conditional builds.

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.