Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR Hydration Isolation

--- description: Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR Hydration Isolation - Nuxt 4 enforces strict separation between the Vue application runtime (app/), the Nitro server engine (server/), and isomorphic code (shared/). Module-level mutable singletons, cross-boundary lifecycle leakage, and improper SSR state hydration cause severe cross-request memory corruption, data leaks across concurrent tenant sessions, and irreversible hydration mismatches. 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-ssr-state-isolation" --- # Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR Hydration Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Poisoning via Module-Scope Variables in Nitro Handlers and Leaky Shared Boundaries ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro v2 invariants. Mandate zero module-level mutable state in Nitro handlers, strictly isolate the app/ runtime from the server/ engine, restrict shared/ code to deterministic pure utilities and types, and ensure SSR hydration safety via request-isolated state primitives. ## Strict Guidelines - Engineers MUST NEVER declare mutable variables (e.g., let, var, new Map(), new Set()) at module scope in server/ routes, Nitro plugins, or shared/ utilities, as node/worker runtimes reuse modules across concurrent requests, causing cross-tenant data leaks. - Engineers MUST ALWAYS store request-scoped metadata exclusively on H3's event.context (e.g., event.context.auth) within Nitro handlers and middleware. - Engineers MUST isolate isomorphic contracts in the shared/ directory, ensuring shared/ modules contain strictly pure functions, type definitions, and schema validators with zero dependencies on Vue reactivity (ref, reactive) or Node.js server intrinsics (fs, path). - Engineers MUST relocate all standard Vue application files into the app/ root directory as required by Nuxt 4 (app/components, app/composables, app/pages, app/middleware), reserving the repository root exclusively for configuration, server/, and shared/. - Engineers MUST ALWAYS use useState() instead of Vue's ref() or reactive() when declaring shared state in app/ composables to guarantee cross-request serialization and prevent SSR hydration mismatches across client-server transitions. - Components NEVER consume Nitro server-only utilities or environment secrets directly; all server operations MUST traverse defineEventHandler endpoints or Nuxt server actions. ## Bad vs Good Implementations ### Cross-Request Pollution in Nitro Event Handler vs Request-Scoped Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `currentUser` at module scope creates a shared memory reference across all incoming HTTP requests in long-lived Node.js or WinterCG worker processes. Under concurrent traffic, Request B reads the profile initialized by Request A, leading to severe tenant identity leakage. ```typescript // server/api/profile.ts import { defineEventHandler, getHeader, createError } from 'h3'; // CRITICAL SECURITY VULNERABILITY: Module-scope mutable state. // Concurrently connected users will overwrite or read each other's credentials. let currentUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const authHeader = getHeader(event, 'authorization'); if (authHeader) { currentUser = await parseToken(authHeader); } if (!currentUser) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } return { user: currentUser }; }); ``` #### Production Standard (Correct) > **Standard**: Eliminates global mutable state entirely. Request-specific values reside purely in local function scope and `event.context`, ensuring total isolation between concurrent requests without memory leaks. ```typescript // server/api/profile.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserProfile } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<{ user: UserProfile }> => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Request-isolated state bound to the single H3 event lifecycle const user = await parseToken(authHeader); event.context.user = user; return { user }; }); ``` ### Un-isolated Composable State vs Nuxt 4 Hydrated useState #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `ref()` at file level outside the composable body makes it global to the Node.js SSR runtime instance. This results in state leakage between different users during SSR rendering and causes Vue hydration mismatch errors on the client. ```typescript // app/composables/useSession.ts import { ref } from 'vue'; // CRITICAL BUG: Global reactive ref outside composable setup function. // State persists across SSR render lifecycles, leaking user session data across SSR requests. const sessionUser = ref<string | null>(null); export const useSession = () => { const setUser = (user: string) => { sessionUser.value = user; }; return { sessionUser, setUser }; }; ``` #### Production Standard (Correct) > **Standard**: Uses `useState('session-user')` inside the composable. Nuxt initializes this state per SSR request, serializes it into the initial payload (__NUXT_DATA__), and seamlessly hydrates it on the client without cross-request contamination. ```typescript // app/composables/useSession.ts import type { Ref } from 'vue'; export const useSession = () => { // Nuxt-managed, SSR-safe reactive state keyed uniquely and serialized safely const sessionUser: Ref<string | null> = useState<string | null>('session-user', () => null); const setUser = (user: string) => { sessionUser.value = user; }; return { sessionUser, setUser }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR Hydration Isolation

Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR Hydration Isolation defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 enforces strict separation between the Vue application runtime (app/), the Nitro server engine (server/), and isomorphic code (shared/). Module-level mutable singletons, cross-boundary lifecycle leakage, and improper SSR state hydration cause severe cross-request memory corruption, data leaks across concurrent tenant sessions, and irreversible hydration mismatches. 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-Request State Poisoning via Module-Scope Variables in Nitro Handlers and Leaky Shared Boundaries 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	Cross-Request State Poisoning via Module-Scope Variables in Nitro Handlers and Leaky Shared Boundaries	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 NEVER declare mutable variables (e.g., let, var, new Map(), new Set()) at module scope in server/ routes, Nitro plugins, or shared/ utilities, as node/worker runtimes reuse modules across concurrent requests, causing cross-tenant data leaks.

Engineers MUST NEVER declare mutable variables (e.g., let, var, new Map(), new Set()) at module scope in server/ routes, Nitro plugins, or shared/ utilities, as node/worker runtimes reuse modules across concurrent requests, causing cross-tenant data leaks.

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.