Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation

--- description: Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation - Enforces strict architectural boundaries between Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state leakage during SSR. Mandates per-request context isolation in Nitro v2 event handlers and SSR-safe reactive singletons via useState. 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/nuxt-4-nitro-shared-directory-ssr-state-isolation" --- # Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Level Shared State Leakage and Cross-Context Boundary Bleed in Nuxt 4 ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 directory structure, Nitro v2 server engine invariants, and Server-Side Rendering (SSR) cross-request state isolation. Prevent shared state leakage, unvalidated runtime boundaries, and legacy Nuxt 3 directory assumptions. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR client state using `useState('uniqueKey', () => initialValue)` inside composables, never top-level module-scoped `ref()` or `reactive()` declarations. - Engineers MUST NOT declare mutable global variables or module-level singletons in `server/` routes, as Nitro worker runtimes reuse memory contexts across concurrent user requests. - Code in the `shared/` directory MUST remain strictly runtime-agnostic: purely deterministic TypeScript types, validation schemas (e.g., Zod), and pure calculation utilities without DOM, Vue reactivity, or Nitro/h3 dependencies. - Engineers MUST NOT import server-only secrets or private `runtimeConfig` into `shared/` or `app/` codebases; sensitive credentials must only be accessed within `server/` using `useRuntimeConfig(event)`. - Nitro server handlers MUST use `defineEventHandler` and retrieve per-request dependencies exclusively via `event.context` or native H3 utilities (`readBody`, `getValidatedQuery`, `createError`). - Nuxt 4 application UI code (components, composables, pages, layouts, plugins) MUST reside under `app/`, completely segregated from `server/` and `shared/`. - SSR state MUST serialize deterministically: avoid non-serializable objects (functions, circular references, complex class instances) in `useState` or `useAsyncData` payloads. ## Bad vs Good Implementations ### SSR Cross-Request State Leakage vs Isolated useState in Nuxt 4 Composable #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `ref()` in the module scope creates a single memory address shared across all concurrent SSR requests in Node.js, leading to severe data leaks across users. ```typescript // app/composables/useUserProfile.ts import { ref } from 'vue'; import type { UserProfile } from '~~/shared/types/user'; // CRITICAL ANTI-PATTERN: Module-scoped state shared across ALL concurrent SSR requests. // User A's profile will leak to User B on simultaneous requests in Node/Nitro worker threads. const globalProfile = ref<UserProfile | null>(null); export const useUserProfile = () => { const setProfile = (profile: UserProfile) => { globalProfile.value = profile; }; return { profile: globalProfile, setProfile, }; }; ``` #### Production Standard (Correct) > **Standard**: `useState` guarantees per-request context isolation on the server and synchronizes state hydration between SSR render and client-side mount without cross-talk. ```typescript // app/composables/useUserProfile.ts import type { UserProfile } from '~~/shared/types/user'; // PRODUCTION INVARIANT: useState binds to the active Nuxt SSR request instance via NuxtApp context. export const useUserProfile = () => { const profile = useState<UserProfile | null>('user-profile-session', () => null); const setProfile = (data: UserProfile) => { profile.value = data; }; const clearProfile = () => { profile.value = null; }; return { profile: readonly(profile), setProfile, clearProfile, }; }; ``` ### Nitro Server Handler Context and Shared Contract Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Imports credentials from shared spaces, violates Nitro H3 event handler conventions, and mutates top-level worker memory, generating memory leaks and concurrent contamination. ```typescript // server/api/users/[id].patch.ts import { sensitiveApiSecret } from '~~/shared/constants'; // Leaking server secret into shared directory let cachedAuditLog: any[] = []; // In-memory mutable global leaking across requests export default (req: any, res: any) => { // Using legacy raw Node request objects instead of Nitro H3 defineEventHandler const id = req.url.split('/').pop(); cachedAuditLog.push({ id, timestamp: Date.now() }); // Memory leak & race conditions return { success: true }; }; ``` #### Production Standard (Correct) > **Standard**: Employs `defineEventHandler`, accesses secrets via `useRuntimeConfig(event)`, leverages `shared/` purely for runtime-agnostic schemas, and isolates per-request data to `event.context`. ```typescript // server/api/users/[id].patch.ts import { UserUpdateSchema } from '~~/shared/schemas/user'; export default defineEventHandler(async (event) => { const config = useRuntimeConfig(event); const userId = getRouterParam(event, 'id'); if (!userId) { throw createError({ statusCode: 400, statusMessage: 'Invalid user identifier', }); } const body = await readValidatedBody(event, (raw) => UserUpdateSchema.safeParse(raw)); if (!body.success) { throw createError({ statusCode: 422, statusMessage: 'Validation Failed', data: body.error.flatten(), }); } // Request context storage avoids module-scope contamination event.context.audit = { userId, updatedBy: event.context.auth?.user?.id ?? 'anonymous', timestamp: Date.now(), }; return { success: true, data: body.data, }; }); ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural boundaries between Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state leakage during SSR. Mandates per-request context isolation in Nitro v2 event handlers and SSR-safe reactive singletons via useState. 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 Shared State Leakage and Cross-Context Boundary Bleed in Nuxt 4 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 Shared State Leakage and Cross-Context Boundary Bleed in Nuxt 4	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 client state using `useState('uniqueKey', () => initialValue)` inside composables, never top-level module-scoped `ref()` or `reactive()` declarations.

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.