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

--- description: Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation - Enforces strict boundary separation between Nuxt 4's app/ directory, Nitro server runtime, and shared/ isomorphic layer. Prevents cross-request state pollution, runtime leakage of server-only secrets into client hydrations, and invalid cross-domain module imports. 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-state-isolation" --- # Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State in Nitro Handlers and Leakage of Server Logic via Shared Directory ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architecture and Nitro v2 invariants. You must prevent cross-request state contamination in Nitro server handlers, mandate correct utilization of the Nuxt 4 app/ and shared/ directory structure, and guarantee SSR state hydration safety. ## Strict Guidelines - Engineers MUST NEVER declare mutable state variables at the module root level in Nitro event handlers (server/*) or composables (app/composables/*), as persistent worker runtimes (Node.js/Bun/Cloudflare Workers) share module scopes across distinct client requests. - Engineers MUST store request-scoped data exclusively within 'event.context' inside Nitro server middleware and routes. - Engineers MUST restrict the top-level 'shared/' directory to purely isomorphic, side-effect-free code (runtime-agnostic data schemas, pure utility functions, and TypeScript types). - Engineers MUST NOT import Nitro server packages (such as 'h3' or Node-specific modules) or Vue/Nuxt client reactivity primitives ('ref', 'computed', 'useState') inside the 'shared/' directory. - Components and composables in 'app/' MUST use 'useState()' instead of global Vue 'ref()' singletons outside of component lifecycles to ensure per-request state hydration isolation during SSR. - Engineers MUST structure all client application code within the 'app/' root directory (including 'app/components', 'app/composables', 'app/pages', 'app/layouts') in compliance with Nuxt 4 specifications. ## Bad vs Good Implementations ### Nitro Server Route State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'currentUserToken' at module root causes a severe race condition and security hole: subsequent concurrent incoming requests overwrite this variable while the previous request is awaiting 'fetchUserProfile', leaking one user's private data to another. ```typescript // server/api/user.ts import { defineEventHandler, getHeader } from 'h3'; // CRITICAL FLAW: Module-level state is shared across all concurrent requests in SSR/Nitro let currentUserToken: string | undefined; export default defineEventHandler(async (event) => { currentUserToken = getHeader(event, 'authorization'); // Asynchronous pause allows concurrent requests to overwrite currentUserToken const userData = await fetchUserProfile(currentUserToken); return { user: userData }; }); async function fetchUserProfile(token?: string) { if (!token) throw new Error('Unauthorized'); return { id: 123, token }; } ``` #### Production Standard (Correct) > **Standard**: Variables are locally scoped to the event handler execution context and 'event.context', ensuring zero state leakage across concurrent incoming requests in long-lived runtime instances. ```typescript // server/api/user.ts import { defineEventHandler, getHeader, createError } from 'h3'; export default defineEventHandler(async (event) => { // Invariant: Request scope is strictly isolated per event invocation or bound to event.context const authorization = getHeader(event, 'authorization'); if (!authorization) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized: Missing authorization header' }); } // Isolate request lifecycle data within event.context if middleware forwarding is required event.context.authToken = authorization; const userData = await fetchUserProfile(event.context.authToken); return { user: userData }; }); async function fetchUserProfile(token: string) { return { id: 123, token }; } ``` ### Nuxt 4 Shared Directory and Composables State Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The 'shared/' directory in Nuxt 4 must remain purely isomorphic. Importing Vue reactivity or H3 types introduces invalid server/client boundary dependencies and risks cross-request memory leaks. ```typescript // shared/types/auth.ts // ANTI-PATTERN: Leaking Vue client reactivity and Nitro internals into isomorphic shared directory import { ref } from 'vue'; import type { H3Event } from 'h3'; export const globalSession = ref<Record<string, unknown> | null>(null); export function setSessionFromEvent(event: H3Event) { globalSession.value = event.context.session; } ``` #### Production Standard (Correct) > **Standard**: The contract in 'shared/' is completely agnostic to runtime frameworks, and the reactive state in 'app/' is initialized via Nuxt's SSR-safe 'useState' composite key, isolating hydration payloads per request. ```typescript // shared/types/auth.ts // INVARIANT: Pure TypeScript contract and schema, free of runtime-specific side effects export interface UserSession { id: string; email: string; roles: readonly string[]; } export function isValidSession(data: unknown): data is UserSession { return typeof data === 'object' && data !== null && 'id' in data && 'email' in data; } // app/composables/useSession.ts // INVARIANT: Nuxt 4 app/ composable leveraging SSR hydration-safe useState key import type { UserSession } from '~~/shared/types/auth'; export const useSession = () => { return useState<UserSession | null>('user-session', () => null); }; ```

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. Enforces strict boundary separation between Nuxt 4's app/ directory, Nitro server runtime, and shared/ isomorphic layer. Prevents cross-request state pollution, runtime leakage of server-only secrets into client hydrations, and invalid cross-domain module imports. 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 in Nitro Handlers and Leakage of Server Logic via Shared Directory 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 in Nitro Handlers and Leakage of Server Logic via Shared Directory	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 NEVER declare mutable state variables at the module root level in Nitro event handlers (server/) or composables (app/composables/), as persistent worker runtimes (Node.js/Bun/Cloudflare Workers) share module scopes across distinct client requests.

Engineers MUST NEVER declare mutable state variables at the module root level in Nitro event handlers (server/*) or composables (app/composables/*), as persistent worker runtimes (Node.js/Bun/Cloudflare Workers) share module scopes across distinct client requests.

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.