Nuxt 4 Nitro SSR State Isolation and Shared Directory Boundary Enforcement

--- description: Nuxt 4 Nitro SSR State Isolation and Shared Directory Boundary Enforcement - Enforces Nuxt 4 architectural segregation across app/, server/, and shared/ directories while strictly eliminating cross-request state pollution in the Nitro engine. Mandates request-scoped lifecycle isolation in SSR routes and prevents runtime leakage of server-only secrets through isomorphic shared layers. 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-directory-state-isolation" --- # Nuxt 4 Nitro SSR State Isolation and Shared Directory Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Mutable Singletons in Nitro Handlers and Impure State Leakage Across Nuxt 4 Boundaries ## System Constraints You are a Principal Software Architect enforcing strict Nuxt 4 and Nitro v2 production guardrails. Nuxt 4 introduces the app/ directory paradigm, Nitro server engine handlers, and a shared/ directory for isomorphic types and pure runtime utilities. You must eliminate cross-request state pollution, reject module-scoped mutable singletons on the server, prevent client exposure of server-only credentials via shared modules, and mandate Nuxt useState for hydration-safe reactive state. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-specific state in Nitro handlers using H3 event context (event.context) or per-handler function closures; module-level mutable variables in server/ are strictly prohibited. - Engineers MUST keep the shared/ directory strictly pure and isomorphic: only deterministic pure utilities, shared data schemas (Zod/Valibot), and TypeScript type contracts are permitted—no database connections, Node.js runtime builtins, or secret access. - Engineers MUST NOT place client-side UI code, Vue SFCs, or Vue composables outside the app/ directory in Nuxt 4 compatibility mode. - Engineers MUST ALWAYS use Nuxt's useState() within app/ composables to avoid multi-tenant state leaks across server-rendered requests; raw module-scoped Vue ref() and reactive() outside component instances are forbidden in SSR. - Engineers MUST validate runtime configurations using useRuntimeConfig(event) inside Nitro routes and ensure private keys residing in runtimeConfig are never imported or referenced in shared/ or app/ code. ## Bad vs Good Implementations ### Nitro Server Handler: Cross-Request State Pollution vs Request-Scoped Event Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`cachedUserSession`) in the module root of a Nitro event handler causes state retention across distinct HTTP requests in persistent Node.js/Bun runtimes, leaking authenticated user context to other users. ```typescript // server/api/user/session.ts - ANTI-PATTERN: Module-level shared mutable state let cachedUserSession: { userId: string; roles: string[] } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token && !cachedUserSession) { // DANGEROUS: Leaks the first authenticated user's session to ALL concurrent SSR requests cachedUserSession = await verifyAndFetchSession(token); } return { user: cachedUserSession }; }); async function verifyAndFetchSession(token: string) { return { userId: '123', roles: ['admin'] }; } ``` #### Production Standard (Correct) > **Standard**: Associating the parsed session directly with `event.context` ensures memory lifecycle is bound exclusively to the incoming HTTP transaction, preventing cross-request pollution. ```typescript // server/api/user/session.ts - PRODUCTION INVARIANT: Request-scoped execution via event context import { createError, defineEventHandler, getHeader } from 'h3'; import type { UserSession } from '~~/shared/types/auth'; declare module 'h3' { interface H3EventContext { userSession?: UserSession; } } export default defineEventHandler(async (event): Promise<{ user: UserSession }> => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Cache strictly within the current request's event context lifecycle if (!event.context.userSession) { event.context.userSession = await verifyAndFetchSession(token); } return { user: event.context.userSession }; }); async function verifyAndFetchSession(token: string): Promise<UserSession> { return { userId: '123', roles: ['admin'] }; } ``` ### Nuxt 4 Shared Directory Isolation vs Impure Secret Leakage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Node-specific modules and accessing private server environments directly inside `shared/` causes bundle failures on the client side and exposes private security keys in client bundles. ```typescript // shared/utils/crypto.ts - ANTI-PATTERN: Exposes server environment and impure state into isomorphic layer import crypto from 'node:crypto'; // Fails or forces heavy polyfills on client const SERVER_SALT = process.env.ENCRYPTION_SALT || 'fallback-secret'; export function hashData(value: string): string { // Leaks secret salt logic and breaks browser bundle compilation return crypto.createHmac('sha256', SERVER_SALT).update(value).digest('hex'); } ``` #### Production Standard (Correct) > **Standard**: Code placed in `shared/` remains strictly deterministic, isomorphic, and free from server-only secrets or client-only DOM APIs, allowing safe consumption by both `server/` and `app/`. ```typescript // shared/utils/validation.ts - PRODUCTION INVARIANT: Pure isomorphic schema import { z } from 'zod'; export const UserProfileSchema = z.object({ username: z.string().min(3).max(32), email: z.string().email(), locale: z.enum(['en', 'es', 'fr']).default('en'), }); export type UserProfile = z.infer<typeof UserProfileSchema>; export function sanitizeUsername(raw: string): string { return raw.trim().toLowerCase(); } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro SSR State Isolation and Shared Directory Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Enforces Nuxt 4 architectural segregation across app/, server/, and shared/ directories while strictly eliminating cross-request state pollution in the Nitro engine. Mandates request-scoped lifecycle isolation in SSR routes and prevents runtime leakage of server-only secrets through isomorphic shared layers. 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 Singletons in Nitro Handlers and Impure State Leakage Across Nuxt 4 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	Global Mutable Singletons in Nitro Handlers and Impure State Leakage Across Nuxt 4 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 handlers using H3 event context (event.context) or per-handler function closures

Engineers MUST ALWAYS isolate request-specific state in Nitro handlers using H3 event context (event.context) or per-handler function closures; module-level mutable variables in server/ are strictly prohibited.

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.