Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standard

--- description: Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standard - Enforces strict boundary isolation across Nuxt 4's app/ directory, Nitro server engine, and shared/ utilities. Prevents catastrophic cross-request state pollution during SSR hydration and ensures clean execution contexts between client, Nitro runtime, and shared code. 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/nuxt-4-nitro-shared-ssr-isolation-standard" --- # Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Module-Level Mutable State Across Concurrent SSR Requests in Nitro Handlers and Shared Utilities ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 standards. You must strictly enforce the Nuxt 4 file hierarchy (app/ directory for client application logic, server/ for Nitro engine, and shared/ for isomorphic contracts). You must prohibit module-level mutable variables in Nitro event handlers and SSR composables to eliminate multi-tenant state leakage. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR state per request using `useState()` inside Vue setup or `event.context` inside Nitro event handlers. - Engineers MUST NOT declare mutable module-scoped variables (e.g., `let currentUser`, `const cache = new Map()`) inside `server/api/`, `server/routes/`, or `server/middleware/` without proper process-isolated tenancy controls. - Engineers MUST locate all frontend application code (components, composables, pages, layouts, plugins, assets) strictly inside the `app/` directory as mandated by Nuxt 4. - Code placed in `shared/` MUST be completely isomorphic, side-effect free, and limited to pure types, validation schemas (e.g., Zod), and deterministic mathematical or transformation functions. - Components and composables MUST NEVER import server-only packages, Node.js built-ins (`fs`, `crypto`, `net`), or Nitro-specific utilities (`defineEventHandler`, `readBody`, `getQuery`). - Nitro server handlers MUST read and write request-specific data exclusively via `H3Event` context (`event.context`) rather than global singletons or process-level memoization. - Composables in `app/composables/` MUST use `useState<T>(key, init)` rather than module-scoped `ref()` or `reactive()` to prevent cross-request state bleeding across incoming SSR invocations. ## Bad vs Good Implementations ### Nitro Server Handler Request Context Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `activeTenantId` in module scope causes a critical multi-tenant data breach. Concurrent requests to this Nitro handler overwrite the variable during asynchronous execution, leaking private tenant data between users. ```typescript // server/api/user/profile.get.ts import { defineEventHandler, getQuery } from 'h3'; // CRITICAL BUG: Module-level state shared across all concurrent HTTP requests! let activeTenantId: string | null = null; export default defineEventHandler(async (event) => { const query = getQuery(event); activeTenantId = query.tenantId as string; // Asynchronous gap allows concurrent requests to overwrite activeTenantId const user = await fetchUserProfileFromDatabase(activeTenantId); return { tenantId: activeTenantId, user }; }); async function fetchUserProfileFromDatabase(tenantId: string) { return { id: 'usr_1', tenantId }; } ``` #### Production Standard (Correct) > **Standard**: The handler validates query parameters using a shared validation schema and binds the transient tenant context directly to `event.context`. The execution state is strictly isolated per incoming request. ```typescript // server/api/user/profile.get.ts import { defineEventHandler, getValidatedQuery, createError } from 'h3'; import { z } from 'zod'; import { TenantQuerySchema } from '~~/shared/utils/validation'; export default defineEventHandler(async (event) => { // Request validation via shared isomorphic contract const { tenantId } = await getValidatedQuery(event, (data) => TenantQuerySchema.parse(data) ); // Request state bound exclusively to H3Event context event.context.tenantId = tenantId; const user = await fetchUserProfileFromDatabase(event.context.tenantId); return { tenantId: event.context.tenantId, user }; }); async function fetchUserProfileFromDatabase(tenantId: string) { return { id: 'usr_1', tenantId }; } ``` ### Nuxt 4 SSR State Hydration vs. Global Scope Leaks #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring a Vue `ref()` outside the composable function creates a singleton inside the SSR server process. Subsequent visitors will inherit the previous user's credentials and hydration state. ```typescript // app/composables/useSession.ts import { ref } from 'vue'; // ANTI-PATTERN: Global ref initialized outside composable scope. // During SSR, this reference persists across requests in the Node.js process. const globalUser = ref<{ id: string; role: string } | null>(null); export function useSession() { const setUser = (user: { id: string; role: string }) => { globalUser.value = user; }; return { user: globalUser, setUser }; } ``` #### Production Standard (Correct) > **Standard**: `useState` provides request-isolated state on the server that serializes seamlessly into the SSR payload and rehydrates on the client without risk of cross-request pollution. ```typescript // app/composables/useSession.ts import type { UserProfile } from '~~/shared/types/auth'; export function useSession() { // useState is SSR-friendly, keyed, and hydrated automatically from server to client per request const user = useState<UserProfile | null>('auth:user_session', () => null); const setUser = (newUser: UserProfile | null) => { user.value = newUser; }; return { user, setUser }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standard

Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation across Nuxt 4's app/ directory, Nitro server engine, and shared/ utilities. Prevents catastrophic cross-request state pollution during SSR hydration and ensures clean execution contexts between client, Nitro runtime, and shared code. 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: Leaking Module-Level Mutable State Across Concurrent SSR Requests in Nitro Handlers and Shared Utilities 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	Leaking Module-Level Mutable State Across Concurrent SSR Requests in Nitro Handlers and Shared Utilities	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 state per request using `useState()` inside Vue setup or `event.context` inside Nitro event 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.