Nuxt 4 Directory Architecture, Nitro Server Isolation, and SSR State Leak Prevention

--- description: Nuxt 4 Directory Architecture, Nitro Server Isolation, and SSR State Leak Prevention - Nuxt 4 strictly enforces a segmented root directory structure where client code resides under app/, server utilities under server/, and universal code under shared/. Failing to isolate SSR execution context or leaking server-only dependencies into shared runtime spaces causes fatal cross-request state contamination, token leakage, and catastrophic client-server hydration divergence. globs: app/**/*.{vue,ts,js}, server/**/*.{ts,js}, shared/**/*.{ts,js}, nuxt.config.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt-4-nitro-shared-ssr-state-isolation-standard" --- # Nuxt 4 Directory Architecture, Nitro Server Isolation, and SSR State Leak Prevention > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Mutable State in Nitro Handlers and Illicit Cross-Boundary Imports between app/, server/, and shared/ ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 Nitro v2 server architecture and SSR hydration safety. Mandate absolute isolation between server/, shared/, and app/ boundaries. Enforce cross-request memory isolation in Nitro event handlers by forbidding module-scoped mutable state. Ensure all universal shared code is purely deterministic and that client state hydration utilizes unique, serializable useState keys. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR and Nitro request lifecycles: NEVER declare module-level mutable variables (let, ref, reactive, Set, Map) in server/routes, server/api, or server/middleware. - Engineers MUST ALWAYS store per-request context inside Nitro's event.context (e.g., event.context.session) or use unctx-wrapped composables within Nuxt's runWithContext scope. - Engineers MUST strictly adhere to Nuxt 4 directory semantics: client application code MUST reside in app/ (pages, components, composables, assets), server endpoints in server/, and purely isomorphic schemas/types in shared/. - Engineers MUST NOT import from server/ inside app/ or shared/, and MUST NOT import Node.js built-in modules or secrets into shared/ or app/. - Engineers MUST ALWAYS pass a unique, deterministic key to useState() and useAsyncData() to prevent SSR hydration collisions across concurrent user requests. - Code inside shared/ MUST be strictly side-effect-free, containing only TypeScript interfaces, Zod/Valibot schemas, pure deterministic mathematical transformations, and universal constants. - Components NEVER store per-request authentication tokens or session payload in persistent module singletons; all state hydrated to client MUST serialize cleanly via devalue without circular references or sensitive credentials. ## Bad vs Good Implementations ### Nitro Server Route State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scoped variables like `currentUserCache` persist across incoming HTTP requests in a long-lived Nitro worker. If Request B arrives before Request A completes or hits the route without re-assigning properly, Request B serves Request A's private tenant data. ```typescript // server/api/user/profile.get.ts // FATAL: Module-level cache leaks sensitive user data across concurrent requests let currentUserCache: { userId: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Pollutes Node/Nitro long-running process across different tenants currentUserCache = await verifyAndFetchUser(token); return { user: currentUserCache }; }); ``` #### Production Standard (Correct) > **Standard**: Per-request context is stored strictly within `event.context` or local function scope. Data validates against a universal schema imported from `shared/`, ensuring zero cross-request memory retention and deterministic serialization. ```typescript // server/api/user/profile.get.ts // SAFE: Scoped directly to Nitro's H3Event context import { z } from 'zod'; import { UserProfileSchema } from '~~/shared/types/user'; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Request context is garbage-collected on request termination const user = await verifyAndFetchUser(token); event.context.user = user; return UserProfileSchema.parse(user); }); ``` ### Nuxt 4 Shared Directory and SSR State Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `ref()` outside the composable function creates a singleton across all concurrent SSR requests on the server, causing User B to see User A's hydrated session. Importing from `server/utils` breaks the Vite client compilation or bundles private server encryption logic to the browser. ```typescript // app/composables/useSession.ts // FATAL: Global reactive ref outside composable scope causes cross-user SSR hydration leak import { ref } from 'vue'; import { decryptSecret } from '~~/server/utils/crypto'; // FATAL: Server import in client bundle const globalUser = ref<{ id: string; secret: string } | null>(null); export const useSession = () => { const setSession = (payload: { id: string; raw: string }) => { // Node crypto breaks in client bundle; ref is shared across all concurrent SSR requests globalUser.value = { id: payload.id, secret: decryptSecret(payload.raw) }; }; return { globalUser, setSession }; }; ``` #### Production Standard (Correct) > **Standard**: `useState` provides scoped hydration bound to the current Nuxt instance via `useNuxtApp()`. Types are safely imported from `shared/`, and server-only cryptographic utilities remain encapsulated within Nitro server routes. ```typescript // app/composables/useSession.ts // SAFE: useState provides isolated SSR-to-client hydration with unique key import type { UserProfile } from '~~/shared/types/user'; export const useSession = () => { // useState is SSR-safe, request-isolated, and auto-hydrated by Nuxt const sessionUser = useState<UserProfile | null>('session:user:profile', () => null); const setSession = (profile: UserProfile) => { sessionUser.value = profile; }; const clearSession = () => { sessionUser.value = null; }; return { sessionUser: readonly(sessionUser), setSession, clearSession }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Architecture, Nitro Server Isolation, and SSR State Leak Prevention

Nuxt 4 Directory Architecture, Nitro Server Isolation, and SSR State Leak Prevention defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 strictly enforces a segmented root directory structure where client code resides under app/, server utilities under server/, and universal code under shared/. Failing to isolate SSR execution context or leaking server-only dependencies into shared runtime spaces causes fatal cross-request state contamination, token leakage, and catastrophic client-server hydration divergence. 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: Global Mutable State in Nitro Handlers and Illicit Cross-Boundary Imports between app/, server/, and shared/ 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	Global Mutable State in Nitro Handlers and Illicit Cross-Boundary Imports between app/, server/, and shared/	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 SSR and Nitro request lifecycles

Engineers MUST ALWAYS isolate SSR and Nitro request lifecycles: NEVER declare module-level mutable variables (let, ref, reactive, Set, Map) in server/routes, server/api, or server/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.