Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Leak Prevention

--- description: Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Leak Prevention - Enforces strict architectural separation between Nitro v2 server routes (server/), isomorphic contracts (shared/), and client application logic (app/) in Nuxt 4. Eliminates critical SSR cross-request state pollution and hydration mismatches caused by module-level mutable variables and illegal runtime imports. globs: app/**/*.{vue,ts,js}, 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-ssr-isolation-shared-boundaries" --- # Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Leak Prevention > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Pollution via Module-Scoped State and Boundary Bleed Between Server, App, and Shared Directories ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architecture and Nitro v2 runtime invariants. Your primary objective is to prevent catastrophic SSR memory leaks, cross-tenant data bleeding, and hydration failures by strictly governing the separation between `app/`, `server/`, and `shared/` directories and banning module-level mutable state in all server-executed code. ## Strict Guidelines - Engineers MUST ALWAYS isolate per-request state in Nitro handlers using H3 event context (`event.context`) or local handler variables; NEVER define top-level mutable module variables. - Engineers MUST structure Vue frontend source code strictly inside the `app/` directory (e.g., `app/components`, `app/composables`, `app/pages`) to comply with Nuxt 4 layout standards. - Engineers MUST restrict the `shared/` directory exclusively to isomorphic utilities, pure functions, and shared TypeScript type contracts; NEVER import runtime Node.js/Nitro modules (`h3`, `nitropack`) or Vue reactivity APIs (`ref`, `reactive`, `useState`) inside `shared/`. - Engineers MUST manage SSR reactive state within Vue components and composables using `useState(key, init)` rather than module-scoped `ref()` or `reactive()` instances to prevent cross-request tenant contamination. - Nitro route handlers MUST return JSON-serializable plain objects or typed responses, ensuring all payload data transferred during Nuxt `useAsyncData` or `useFetch` hydrates cleanly without serialization truncation. - Server-only logic, database connections, and secrets MUST strictly reside within `server/` and MUST NEVER be referenced directly or indirectly by code in `app/` or `shared/`. ## Bad vs Good Implementations ### Nitro Server Route Request State Isolation vs. Module-Level Data Leakage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scoped variables in Nitro server routes persist across concurrent and subsequent HTTP requests within the same Node/Worker runtime. Multiple incoming requests overwrite `currentUserToken` and reuse `cachedUserProfile`, causing catastrophic multi-tenant data leaks and race conditions. ```typescript // server/api/user/profile.ts import { defineEventHandler, getHeader } from 'h3'; // CRITICAL ANTI-PATTERN: Module-level mutable state shared across all concurrent SSR requests let currentUserToken: string | undefined; let cachedUserProfile: Record<string, unknown> | null = null; export default defineEventHandler(async (event) => { currentUserToken = getHeader(event, 'authorization'); if (currentUserToken && !cachedUserProfile) { // Multiple concurrent requests overwrite currentUserToken, leading to data bleeding between tenants cachedUserProfile = await fetchUserDataFromDb(currentUserToken); } return { profile: cachedUserProfile }; }); async function fetchUserDataFromDb(token: string) { return { id: 1, token }; } ``` #### Production Standard (Correct) > **Standard**: Per-request data is strictly scoped to local handler execution and standard H3 `event.context`. Shared contracts are imported from `shared/types/user`, keeping the handler pure, concurrent-safe, and deterministic. ```typescript // server/api/user/profile.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserProfile } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<{ profile: UserProfile }> => { const authorization = getHeader(event, 'authorization'); if (!authorization) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized access: Bearer token required' }); } // Per-request isolation: store context strictly on event.context or in local variables const profile = await fetchUserDataFromDb(authorization); event.context.user = profile; return { profile }; }); async function fetchUserDataFromDb(token: string): Promise<UserProfile> { return { id: 'usr_102', role: 'member', tokenHash: token.slice(-6) }; } ``` ### Nuxt 4 Composable SSR State Isolation vs. Module-Level Vue Ref #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `ref` or `reactive` in module scope creates a single singleton across the entire server process. When Request A logs in User A, User B's SSR render will inherit User A's session, resulting in security vulnerabilities and client-side hydration mismatches. ```typescript // app/composables/useUserSession.ts import { ref } from 'vue'; // CRITICAL ANTI-PATTERN: Module-level Vue reactivity leaks state between requests in SSR const userSession = ref<{ id: string; name: string } | null>(null); export function useUserSession() { const setSession = (data: { id: string; name: string }) => { userSession.value = data; }; const clearSession = () => { userSession.value = null; }; return { userSession, setSession, clearSession }; } ``` #### Production Standard (Correct) > **Standard**: Nuxt's `useState` hooks directly into the active Nuxt SSR instance payload (`nuxtApp.payload.state`), ensuring complete isolation between concurrent user requests and zero-mismatch client-side hydration. ```typescript // app/composables/useUserSession.ts import type { UserSession } from '~~/shared/types/user'; export function useUserSession() { // useState guarantees request-isolated, SSR-safe reactive state keyed uniquely const userSession = useState<UserSession | null>('user-session-state', () => null); const setSession = (data: UserSession) => { userSession.value = data; }; const clearSession = () => { userSession.value = null; }; return { userSession: readonly(userSession), setSession, clearSession }; } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Leak Prevention defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural separation between Nitro v2 server routes (server/), isomorphic contracts (shared/), and client application logic (app/) in Nuxt 4. Eliminates critical SSR cross-request state pollution and hydration mismatches caused by module-level mutable variables and illegal runtime imports. 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 Pollution via Module-Scoped State and Boundary Bleed Between Server, App, and Shared Directories 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 Pollution via Module-Scoped State and Boundary Bleed Between Server, App, and Shared Directories	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 per-request state in Nitro handlers using H3 event context (`event.context`) or local handler variables

Engineers MUST ALWAYS isolate per-request state in Nitro handlers using H3 event context (`event.context`) or local handler variables; NEVER define top-level mutable module variables.

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.