Nuxt 4 Nitro SSR Request Isolation and Shared Directory Boundary Enforcement

--- description: Nuxt 4 Nitro SSR Request Isolation and Shared Directory Boundary Enforcement - Enforces strict runtime boundary isolation between Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state pollution in Nitro v2 server handlers. Mandates request-scoped context via event.context and hydration-safe SSR primitives via useState() to block concurrent memory leaks and credential bleed. 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-context-isolation-and-shared-boundaries" --- # Nuxt 4 Nitro SSR Request Isolation and Shared Directory Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Scope Singleton State Leaking Across Nitro Requests and Secret Bleed Across Shared Boundaries ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro v2 architecture standards. Mandate strict directory isolation (app/, server/, shared/), eradicate cross-request state pollution in Nitro SSR, ensure memory safety across concurrent requests, and enforce safe hydration boundaries. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-specific state in Nitro event handlers using event.context or return values instead of module-scoped variables. - Engineers MUST NOT declare mutable global singletons, module-level state, or Vue reactive primitives (ref, reactive) inside server/ or shared/ directories. - Engineers MUST strictly restrict the shared/ directory to pure, stateless code (e.g., schemas, type definitions, deterministic pure validation functions) without Node.js, server runtime, or client-specific dependencies. - Code inside app/ MUST NEVER directly import files from the server/ directory to prevent compilation failures, Node runtime leaks, or bundling server secrets into the client bundle. - Code MUST use Nuxt's useState() or useAsyncData() exclusively inside app/ for SSR state hydration to guarantee request-unique serializability and avoid hydration mismatches. - Nitro server routes MUST consume runtime configuration strictly via useRuntimeConfig(event), distinguishing public variables from server-only private variables. - Nitro middleware and handlers MUST handle per-request teardown deterministically without attaching persistent event listeners to global process or runtime emitter singletons. ## Bad vs Good Implementations ### Nitro Server Handler Request Context vs. Module-Level Pollution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In long-running Node or Nitro serverless runtimes, module-level variables persist across concurrent incoming requests. Concurrent requests cause data contamination, allowing User B to receive User A's profile or permission escalation. ```typescript // server/api/auth/profile.get.ts // ANTI-PATTERN: Module-level mutable state leaks across concurrent requests in long-running Nitro process let activeSessionUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, message: 'Unauthenticated' }); } // Race condition: Next request will overwrite or read another tenant's session state activeSessionUser = await resolveUserSession(token); return { user: activeSessionUser }; }); ``` #### Production Standard (Correct) > **Standard**: Request data is scoped purely to the ephemeral H3 event lifecycle and returned directly, eliminating shared-memory cross-request tenant leakage. ```typescript // server/api/auth/profile.get.ts // PRODUCTION-READY: Request-scoped execution bound strictly to Nitro H3 event context export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } const sessionUser = await resolveUserSession(token); // Safely assign request-scoped context for downstream middleware or logging event.context.user = sessionUser; return { user: sessionUser }; }); ``` ### Nuxt 4 Shared Directory Boundary vs. Runtime Leakage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Placing Node-specific dependencies, server environment variable accesses, or mutable global caches into Nuxt 4's shared/ directory breaks isomorphic builds, leaks credentials to client bundles, and creates un-isolated runtime states. ```typescript // shared/utils/auth.ts // ANTI-PATTERN: Mixing server runtime dependencies and client code in shared/ import jwt from 'jsonwebtoken'; // Server-only dependency packaged into client bundle! export const userTokenCache = new Map<string, unknown>(); // Mutable shared singleton export function verifyAndExtract(token: string) { const secret = process.env.JWT_SECRET; // Undefined on client hydration return jwt.verify(token, secret as string); } ``` #### Production Standard (Correct) > **Standard**: Nuxt 4 shared/ directory remains completely stateless, runtime-agnostic, and safe for isomorphic compilation across Nitro server routes and Vue client components. ```typescript // shared/schemas/auth.ts // PRODUCTION-READY: Pure, isomorphic, stateless schema and contract definitions import { z } from 'zod'; export const UserProfileSchema = z.object({ id: z.string().uuid(), email: z.string().email(), role: z.enum(['admin', 'member', 'guest']) }); export type UserProfile = z.infer<typeof UserProfileSchema>; export function sanitizeUsername(username: string): string { return username.trim().toLowerCase(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro SSR Request Isolation and Shared Directory Boundary Enforcement

Nuxt 4 Nitro SSR Request Isolation and Shared Directory Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime boundary isolation between Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state pollution in Nitro v2 server handlers. Mandates request-scoped context via event.context and hydration-safe SSR primitives via useState() to block concurrent memory leaks and credential bleed. 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-Scope Singleton State Leaking Across Nitro Requests and Secret Bleed Across 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	Module-Scope Singleton State Leaking Across Nitro Requests and Secret Bleed Across 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 ALWAYS isolate request-specific state in Nitro event handlers using event.context or return values instead of module-scoped 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.