AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
frontendcritical PriorityID: vite6-multi-runtime-hydration-integrity

Vite 6 Environment API Multi-Runtime Hydration Integrity and Module Isolation Guardrail

Enforces deterministic module evaluation, condition resolution, and state isolation across heterogeneous runtime targets (Node.js, Edge Workers, and Browser) via the Vite 6 Environment API. Prevents cross-environment module graph leakage, single-binary state contamination, and runtime-induced hydration discrepancies during simultaneous multi-runtime builds.

Prohibited Anti-Pattern: Cross-Runtime Module Graph Contamination and Non-Deterministic Hydration Failure

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Vite 6 Environment API Multi-Runtime Hydration Integrity and Module Isolation Guardrail - Enforces deterministic module evaluation, condition resolution, and state isolation across heterogeneous runtime targets (Node.js, Edge Workers, and Browser) via the Vite 6 Environment API. Prevents cross-environment module graph leakage, single-binary state contamination, and runtime-induced hydration discrepancies during simultaneous multi-runtime builds.
globs: vite.config.ts, vite.config.mts, src/**/*.{ts,tsx}, server/**/*.{ts,tsx}, edge/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/vite6-multi-runtime-hydration-integrity"
---

# Vite 6 Environment API Multi-Runtime Hydration Integrity and Module Isolation Guardrail

> **Severity**: CRITICAL | **Category**: frontend
> **Anti-Pattern Warning**: Cross-Runtime Module Graph Contamination and Non-Deterministic Hydration Failure

## System Constraints
You are a Principal Software Architect enforcing Vite 6 Environment API architecture and multi-runtime SSR hydration invariants. Your objective is to eliminate non-deterministic module resolution, shared memory pollution between runtime graphs (Node.js vs. Web-compatible Edge isolates like workerd), and hydration mismatches. You must mandate discrete environment declarations, forbid legacy Vite SSR patterns (such as Boolean ssr flags and ssrLoadModule), and ensure that every runtime environment isolates its module evaluation and serialization boundaries.

## Strict Guidelines
- Engineers MUST ALWAYS configure discrete environments under the Vite 6 `environments` object (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic root SSR flags.
- Plugins MUST inspect `this.environment.name` or `this.environment.mode` within hooks, and MUST NOT rely on deprecated legacy `options.ssr` boolean checks.
- Engineers MUST declare explicit, runtime-differentiated `resolve.conditions` and `resolve.noExternal` rules for each runtime environment to prevent Node.js built-ins from entering edge worker bundles.
- Shared UI components rendered across runtimes MUST NOT access ambient runtime-specific globals (`process.env`, `global`, `Deno`, `caches`) without defensive environment abstraction contracts.
- State containers serialized during edge or Node SSR passes MUST emit strict, deterministic JSON payloads that match client-side bootstrap schemas byte-for-byte to prevent hydration panic.
- Engineers MUST NEVER share mutable singletons or module-scoped caches across multiple Vite 6 runner contexts in the same Node.js orchestrator process.

## Bad vs Good Implementations
### Vite 6 Multi-Runtime Environment Isolation vs Legacy SSR Config

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Using legacy root `ssr` configurations and checking `options.ssr` fails in Vite 6 multi-runtime setups. It causes module graph contamination when targeting both Node.js (for toolchains/SSR) and edge workers (like Cloudflare/workerd), leading to build-time leaks of Node built-ins into worker bundles and broken hydration parity.
```typescript
import { defineConfig } from 'vite';

// ANTI-PATTERN: Vite 5 legacy SSR configuration conflating Node and Edge runtimes
export default defineConfig({
  ssr: {
    // Ambiguous target: attempts to serve both Cloudflare Edge and Node SSR
    target: 'webworker',
    noExternal: true,
  },
  plugins: [
    {
      name: 'env-middleware',
      transform(code, id, options) {
        // Deprecated: boolean check ignores target runtime specifics
        if (options?.ssr) {
          return code.replace('__RUNTIME__', '"server"');
        }
        return code.replace('__RUNTIME__', '"client"');
      },
    },
  ],
});
```

#### Production Standard (Correct)
> **Standard**: This configuration utilizes the Vite 6 Environment API to create partitioned module graphs for `client`, `ssr` (Node), and `edge` (Workerd). Plugins inspect `this.environment.name`, ensuring completely isolated resolve conditions, correct target externals, and deterministic compilation without cross-runtime leaks.
```typescript
import { defineConfig } from 'vite';
import { createRunnableDevEnvironment } from 'vite';

// PRODUCTION PATTERN: Vite 6 Environment API with isolated runtime configurations
export default defineConfig({
  environments: {
    client: {
      consumer: 'client',
      resolve: {
        conditions: ['browser', 'import', 'module'],
      },
      build: {
        outDir: 'dist/client',
      },
    },
    ssr: {
      consumer: 'server',
      resolve: {
        conditions: ['node', 'import', 'module'],
        external: ['stream', 'crypto', 'path'],
      },
      build: {
        outDir: 'dist/ssr',
        target: 'node22',
      },
    },
    edge: {
      consumer: 'server',
      resolve: {
        conditions: ['worker', 'workerd', 'browser', 'import'],
        noExternal: true,
      },
      build: {
        outDir: 'dist/edge',
        target: 'esnext',
      },
    },
  },
  plugins: [
    {
      name: 'runtime-aware-evaluator',
      transform(code, id) {
        // Deterministic transformation partitioned by Vite 6 environment name
        const envName = this.environment.name;
        if (envName === 'edge') {
          return code.replaceAll('__ENVIRONMENT_TARGET__', JSON.stringify('edge'));
        }
        if (envName === 'ssr') {
          return code.replaceAll('__ENVIRONMENT_TARGET__', JSON.stringify('node'));
        }
        return code.replaceAll('__ENVIRONMENT_TARGET__', JSON.stringify('client'));
      },
    },
  ],
});
```

### Deterministic Cross-Runtime Hydration State Boundary

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Directly referencing runtime-specific singletons and non-deterministic dynamic variables creates divergent DOM trees between server compilation (Node or Edge) and client rehydration, causing immediate React hydration failures and layout shifts.
```typescript
import React from 'react';

// ANTI-PATTERN: Reading ambient runtime globals directly inside isomorphic components
export function HydratedMetric({ label }: { label: string }) {
  // Leaks Node/Edge runtime differences directly to client markup -> Hydration Mismatch
  const timestamp = typeof process !== 'undefined' && process.uptime 
    ? `node-${process.uptime()}` 
    : `edge-${Date.now()}`;

  return (
    <div className="metric">
      <span>{label}</span>
      <span>{timestamp}</span>
    </div>
  );
}
```

#### Production Standard (Correct)
> **Standard**: Guarantees cross-runtime hydration integrity by enforcing a strict context boundary. The server snapshot is computed once per request at the entry router layer, serialized consistently regardless of whether Node.js or Edge executed it, and hydrated deterministically on the client.
```typescript
import React, { createContext, useContext, useId } from 'react';

interface RuntimeSnapshot {
  deterministicSeed: string;
  epochMs: number;
}

const HydrationContext = createContext<RuntimeSnapshot | null>(null);

export function HydrationBoundary({
  snapshot,
  children,
}: {
  snapshot: RuntimeSnapshot;
  children: React.ReactNode;
}) {
  return (
    <HydrationContext.Provider value={snapshot}>
      {children}
    </HydrationContext.Provider>
  );
}

export function HydratedMetric({ label }: { label: string }) {
  const context = useContext(HydrationContext);
  const stableId = useId();

  if (!context) {
    throw new Error('HydratedMetric must be rendered within a valid HydrationBoundary');
  }

  return (
    <div className="metric" id={stableId}>
      <span>{label}</span>
      <time dateTime={new Date(context.epochMs).toISOString()}>
        {context.deterministicSeed}
      </time>
    </div>
  );
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Vite DevTools Inspection Protocol
Inspects Vite 6 runtime environment graphs, active plugins per environment, and active dev runners.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Verify Vite 6 Multi-Environment Build
Executes simultaneous client, ssr, and edge compilation targets to detect condition mismatches and runtime leaks.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime Hydration Integrity and Module Isolation Guardrail

Vite 6 Environment API Multi-Runtime Hydration Integrity and Module Isolation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic module evaluation, condition resolution, and state isolation across heterogeneous runtime targets (Node.js, Edge Workers, and Browser) via the Vite 6 Environment API. Prevents cross-environment module graph leakage, single-binary state contamination, and runtime-induced hydration discrepancies during simultaneous multi-runtime builds. 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: Cross-Runtime Module Graph Contamination and Non-Deterministic Hydration Failure 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftCross-Runtime Module Graph Contamination and Non-Deterministic Hydration FailureCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS configure discrete environments under the Vite 6 `environments` object (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic root SSR flags.

Engineers MUST ALWAYS configure discrete environments under the Vite 6 `environments` object (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic root SSR 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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Plugins MUST inspect `this.environment.name` or `this.environment.mode` within hooks, and MUST NOT rely on deprecated legacy `options.ssr` boolean checks.

Plugins MUST inspect `this.environment.name` or `this.environment.mode` within hooks, and MUST NOT rely on deprecated legacy `options.ssr` boolean checks.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST declare explicit, runtime-differentiated `resolve.conditions` and `resolve.noExternal` rules for each runtime environment to prevent Node.js built-ins from entering edge worker bundles.

Engineers MUST declare explicit, runtime-differentiated `resolve.conditions` and `resolve.noExternal` rules for each runtime environment to prevent Node.js built-ins from entering edge worker bundles.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Shared UI components rendered across runtimes MUST NOT access ambient runtime-specific globals (`process.env`, `global`, `Deno`, `caches`) without defensive environment abstraction contracts.

Shared UI components rendered across runtimes MUST NOT access ambient runtime-specific globals (`process.env`, `global`, `Deno`, `caches`) without defensive environment abstraction contracts.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

State containers serialized during edge or Node SSR passes MUST emit strict, deterministic JSON payloads that match client-side bootstrap schemas byte-for-byte to prevent hydration panic.

State containers serialized during edge or Node SSR passes MUST emit strict, deterministic JSON payloads that match client-side bootstrap schemas byte-for-byte to prevent hydration panic.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Engineers MUST NEVER share mutable singletons or module-scoped caches across multiple Vite 6 runner contexts in the same Node.js orchestrator process.

Engineers MUST NEVER share mutable singletons or module-scoped caches across multiple Vite 6 runner contexts in the same Node.js orchestrator process.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Vite 6 Environment API Multi-Runtime Hydration Integrity and Module Isolation Guardrail critical for AI coding assistants?

Enforces deterministic module evaluation, condition resolution, and state isolation across heterogeneous runtime targets (Node.js, Edge Workers, and Browser) via the Vite 6 Environment API. Prevents cross-environment module graph leakage, single-binary state contamination, and runtime-induced hydration discrepancies during simultaneous multi-runtime builds. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Cross-Runtime Module Graph Contamination and Non-Deterministic Hydration Failure) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related FRONTEND Rules

View all rules →
frontend
119

SolidStart 1.0 Server Functions & Async Boundaries Production Standard

SolidStart 1.0 relies on the Vinxi bundler to split `server$` closures into independent HTTP POST RPC endpoints. Direct lexical closure over client signals within `server$` scopes or failure to demarcate async boundaries with `<Suspense>` causes silent serialization failures, client-bundle secret leaks, and SSR hydration mismatches. Enforcing strict parameter passing, runtime input validation, and Solid async primitives maintains security and fine-grained reactivity across network boundaries.

frontend
119

Astro 5 Actions & Content Layer Production Standard

Enforces strict type safety and architectural correctness for Astro 5 Server Actions and the zero-waterfall Content Layer API. Prevents runtime contract mismatches, hydration mismatches, and unhandled mutation exceptions across dynamic and prerendered boundaries. Failure to follow these patterns leads to silent data fetching waterfalls, build-time cache corruptions, and unhandled server action exceptions.

frontend
51

Nuxt 4 Nitro Server Engine & Shared Directory Production Standard

Nuxt 4 enforces strict boundary segregation between client UI in the app/ directory, backend endpoints in server/, and universal contracts in shared/. Violating cross-boundary isolation or maintaining module-scoped state in Nitro server handlers causes catastrophic cross-request data corruption and hydration mismatches under concurrent production traffic. Architects must enforce request-isolated H3 event contexts, universal serialization schemas, and strict path-alias boundaries.

1 Rule in Stack

Vite