Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration

--- description: Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration - Enforces strict architectural isolation across Nuxt 4 app/, server/, and shared/ directory boundaries to prevent cross-request state pollution in Nitro and SSR hydration mismatches. Prohibits module-scoped state in Nitro route handlers and guarantees shared/ contains only runtime-agnostic, side-effect-free code devoid of server secrets or client-only APIs. globs: app/**/*.{ts,vue}, server/**/*.{ts,js}, shared/**/*.{ts,js}, nuxt.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt4-nitro-shared-directory-isolation-guardrail" --- # Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Level Nitro State Leakage and Shared Directory Secret Contamination Causing SSR Hydration Mismatches ## System Constraints You are a Principal Software Architect enforcing production safety in Nuxt 4 applications. You must strictly govern the tripartite directory model (app/, server/, shared/), eradicate cross-request state pollution in Nitro event handlers, prevent server secret leaks via shared code, and eliminate SSR hydration corruption caused by unpinned or non-serializable state. ## Strict Guidelines - Engineers MUST ALWAYS isolate Nitro request state using `event.context` or explicit parameters; NEVER declare mutable module-scoped variables (`let`, `new Map()`, `ref()`) inside `server/` routes, utilities, or middleware. - Engineers MUST confine all client-side Vue source files to the `app/` directory (e.g., `app/pages`, `app/components`, `app/composables`), keeping `server/` strictly for Nitro APIs, tasks, and middleware. - Engineers MUST keep the `shared/` directory 100% runtime-agnostic and free of side effects; NEVER import `vue`, Node.js built-ins (`fs`, `crypto`, `path`), Nitro runtime utilities, or server runtime config into `shared/`. - Engineers MUST ALWAYS manage SSR-hydrated reactive state with `useState(key, init)` in `app/composables/`; module-level `ref()`, `reactive()`, or global singletons in app code MUST NEVER be used as they cause cross-request tenant data leaks during SSR. - Engineers MUST guarantee all payloads returned by `server/api/*` and consumed by `useAsyncData` or `useFetch` are JSON-serializable primitives, plain objects, or arrays; NEVER serialize class instances, functions, circular structures, or un-sanitized server metadata. - Engineers MUST pass an explicit and deterministic key to `useAsyncData` when invoked conditionally or dynamically to prevent mismatching hydration states between SSR rendering and client-side mount. ## Bad vs Good Implementations ### Nitro Server Route State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scoped variables in Nitro persist across concurrent requests on Node.js and long-running serverless workers. Caching user sessions in module scope causes catastrophic cross-request state contamination where Request B receives credentials or state loaded by Request A. ```typescript // server/api/user/session.ts // FATAL: Module-scoped state shared across all concurrent requests (cross-tenant leak) let activeSessionCache: Record<string, any> = {}; export default defineEventHandler(async (event) => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) throw createError({ statusCode: 401 }); if (!activeSessionCache[authHeader]) { activeSessionCache[authHeader] = await fetchSessionFromDB(authHeader); } return activeSessionCache[authHeader]; }); ``` #### Production Standard (Correct) > **Standard**: Attaching intermediate state to `event.context` guarantees strict request lifecycles. Once the Nitro HTTP response terminates, the context is garbage-collected, preventing data leakage across concurrent server connections. ```typescript // server/api/user/session.ts // SECURE: Stateless handler binding request-scoped data to Nitro event context export default defineEventHandler(async (event) => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Per-request isolation via event.context, or Nitro useStorage() with proper key isolation if (!event.context.userSession) { const session = await fetchSessionFromDB(authHeader); event.context.userSession = session; } return event.context.userSession; }); ``` ### Nuxt 4 Shared Directory Boundaries & SSR State Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `shared/` is bundled into both client and Nitro output. Importing `node:crypto` and referencing `process.env.SERVER_SECRET` breaks client builds or leaks production secrets to browser bundles. Additionally, module-level `ref` in composables leaks state between SSR requests. ```typescript // shared/utils/user.ts // FATAL: Leaks server environment secrets and imports Node built-in to code shared with client import { createHmac } from 'node:crypto'; export const hashToken = (token: string) => { const secret = process.env.SERVER_SECRET || 'fallback'; return createHmac('sha256', secret).update(token).digest('hex'); }; // app/composables/useUserProfile.ts // FATAL: Module-level ref causes SSR cross-request memory leak and hydration mismatches const globalProfile = ref<UserProfile | null>(null); export const useUserProfile = () => { return { profile: globalProfile }; }; ``` #### Production Standard (Correct) > **Standard**: `shared/` contains only runtime-agnostic contracts, validation logic, and shared types. The composable uses `useState()` with a unique key, ensuring Vue's hydration pipeline captures and isolates state per SSR request without cross-tenant memory leaks. ```typescript // shared/types/user.ts // COMPLIANT: Pure TypeScript interfaces and runtime-agnostic schemas export interface UserProfile { id: string; username: string; roles: readonly string[]; } export const isValidUsername = (name: string): boolean => { return /^[a-zA-Z0-9_-]{3,16}$/.test(name); }; // app/composables/useUserProfile.ts // COMPLIANT: Request-scoped SSR state isolated with Nuxt useState import type { UserProfile } from '~~/shared/types/user'; export const useUserProfile = () => { const profile = useState<UserProfile | null>('user-profile-key', () => null); return { profile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration

Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural isolation across Nuxt 4 app/, server/, and shared/ directory boundaries to prevent cross-request state pollution in Nitro and SSR hydration mismatches. Prohibits module-scoped state in Nitro route handlers and guarantees shared/ contains only runtime-agnostic, side-effect-free code devoid of server secrets or client-only APIs. 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: Module-Level Nitro State Leakage and Shared Directory Secret Contamination Causing SSR Hydration Mismatches 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	Module-Level Nitro State Leakage and Shared Directory Secret Contamination Causing SSR Hydration Mismatches	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 isolate Nitro request state using `event.context` or explicit parameters

Engineers MUST ALWAYS isolate Nitro request state using `event.context` or explicit parameters; NEVER declare mutable module-scoped variables (`let`, `new Map()`, `ref()`) inside `server/` routes, utilities, or middleware.

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.