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

--- description: Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation - Mandates strict architectural separation across Nuxt 4's app/, server/, and shared/ directories to prevent server-side runtime leakage and cross-request state pollution (CRSP). Enforces isomorphic purity in shared/, request-scoped lifecycle handling in Nitro handlers, and SSR-safe state hydration via useState. 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-shared-ssr-boundary-isolation" --- # Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State Pollution and Cross-Boundary Runtime Leakage in Nuxt 4 ## System Constraints You are a Principal Architect enforcing Nuxt 4 directory restructuring, Nitro v2 server lifecycle rules, and SSR state isolation. Enforce absolute purity in shared/, request isolation in Nitro handlers, and prevent cross-request state leakage across multi-tenant server renders. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-specific state in Nuxt 4 using useState() in app/ and event.context in Nitro server/ handlers. - Engineers MUST NOT declare mutable module-level state (let variables, ref(), reactive(), new Map(), or singleton instances) in the top-level scope of server routes, composables, or shared/ modules. - Code in the root shared/ directory MUST remain strictly isomorphic and pure: zero references to browser globals (window, document, localStorage) and zero references to server runtime globals or Node.js built-ins (fs, path, process.env). - Server code under server/ MUST NEVER be imported into app/, and frontend UI code under app/ MUST NEVER be imported into server/; shared types, constants, and pure deterministic utilities MUST reside strictly in shared/. - Nitro route handlers MUST ALWAYS return validated data structures and handle operational failures using createError({ statusCode, statusMessage }) rather than unhandled promise rejections or raw thrown errors. - Components and composables in app/ MUST NEVER initiate synchronous file operations, direct database queries, or store secrets meant for runtimeConfig (Nitro server-only keys). ## Bad vs Good Implementations ### Module-Level Shared State vs. Request-Scoped Nitro & Nuxt Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`activeSession`, `cachedUserCount`) at the top level of shared modules or Nitro handlers causes Cross-Request State Pollution (CRSP). In Node.js/Nitro SSR, server instances are persistent processes; global mutations leak tenant data between different users' requests. Throwing raw Error instances instead of createError leaks internal stack traces. ```typescript // shared/types/session.ts - ANTI-PATTERN: Mutable module singleton in shared space export interface UserSession { userId: string; token: string; } // Leaking shared state across SSR requests export let activeSession: UserSession | null = null; export const setSession = (s: UserSession) => { activeSession = s; }; // server/api/profile.get.ts - ANTI-PATTERN: Cross-request state pollution and unhandled context import { activeSession, setSession } from '~/shared/types/session'; import fs from 'node:fs'; // Node API directly coupled let cachedUserCount = 0; // Shared state leak across ALL users/requests on Nitro! export default defineEventHandler(async (event) => { cachedUserCount++; const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw new Error('Unauthorized'); // Unhandled runtime 500 error leak } setSession({ userId: '123', token: authHeader }); return { session: activeSession, totalQueries: cachedUserCount }; }); ``` #### Production Standard (Correct) > **Standard**: Types are shared purely without side-effects. The Nitro server handler stores state strictly within the execution scope of the incoming `H3Event`, throwing standard H3 errors with HTTP statuses. On the client/SSR boundary, `useState` ensures per-request state hydration without leaking memory or tenant data across multi-user server requests. ```typescript // shared/types/session.ts - Pure, isomorphic contract export interface UserSession { readonly userId: string; readonly token: string; } export interface ProfileResponse { session: UserSession; } // server/api/profile.get.ts - Request-scoped Nitro handler import type { ProfileResponse, UserSession } from '@@/shared/types/session'; export default defineEventHandler(async (event): Promise<ProfileResponse> => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized', message: 'Valid Authorization header is required.' }); } // Request-scoped storage via Nitro event context const userSession: UserSession = { userId: event.context.auth?.userId ?? 'anonymous', token: authHeader }; return { session: userSession }; }); // app/composables/useUserSession.ts - SSR-safe hydration via useState import type { UserSession } from '@@/shared/types/session'; export const useUserSession = () => { const session = useState<UserSession | null>('user-session', () => null); const fetchSession = async () => { const { data, error } = await useFetch<ProfileResponse>('/api/profile'); if (error.value) throw error.value; if (data.value) session.value = data.value.session; }; return { session: readonly(session), fetchSession }; }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Mandates strict architectural separation across Nuxt 4's app/, server/, and shared/ directories to prevent server-side runtime leakage and cross-request state pollution (CRSP). Enforces isomorphic purity in shared/, request-scoped lifecycle handling in Nitro handlers, and SSR-safe state hydration 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: Global Module-Level State Pollution and Cross-Boundary Runtime Leakage 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	Global Module-Level State Pollution and Cross-Boundary Runtime Leakage 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 request-specific state in Nuxt 4 using useState() in app/ and event.context in Nitro server/ handlers.

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.