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 isolation between Nuxt 4 client code in app/, Nitro v2 engine routes in server/, and universal utilities in shared/. Mandates per-request context isolation to eliminate multi-tenant cross-request state pollution and hydration mismatches during server-side rendering (SSR). 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" --- # 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 Direct Server Module Leakage into Client Hydration ## System Constraints You are a Principal Software Architect enforcing production Nuxt 4 and Nitro v2 patterns. You must prevent global state retention across requests in Nitro server engines, enforce the Nuxt 4 directory structure (app/, server/, shared/), eliminate SSR memory leaks, and guarantee safe, deterministic client-side hydration. ## Strict Guidelines - Engineers MUST ALWAYS structure Nuxt 4 applications using the app/ folder for UI logic, server/ for Nitro routes and middleware, and shared/ exclusively for pure isomorphic utilities and contracts. - Engineers MUST NOT declare mutable variables at the module or file root in server/ handlers or shared/ utilities, as Nitro persists the Node.js/V8 runtime instance across subsequent concurrent requests. - Code MUST access request-specific execution contexts strictly via H3 utilities (e.g., event.context, getRouterParam, readBody, getQuery) rather than external closures. - Components and composables MUST use useState() or Nuxt-managed stores for isomorphic data initialization; components MUST NEVER initialize state with non-deterministic values (like Date.now() or Math.random()) during SSR without pre-seeding via useAsyncData(). - Services in shared/ MUST remain pure, free of Node.js-only builtins (fs, crypto, path) or client-only APIs (window, document, localStorage), ensuring runtime safety across both Nitro and the browser. - Engineers MUST wrap all Nitro event handlers using defineEventHandler() and return serialized, structured payloads without circular references to prevent SSR hydration crashes. ## Bad vs Good Implementations ### State Leakage in Nitro v2 Event Handler vs Request-Scoped Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scope variables in Nitro stay resident in the V8 process across different HTTP requests, leaking credentials and state between concurrent users. ```typescript // server/api/user-session.ts import { defineEventHandler, getHeader } from 'h3'; // CRITICAL ANTI-PATTERN: Shared module-level state leaks between concurrent HTTP requests let currentUserSession: { token: string | undefined; accessedAt: number } | null = null; export default defineEventHandler((event) => { const authHeader = getHeader(event, 'authorization'); currentUserSession = { token: authHeader, accessedAt: Date.now() }; // If another request arrives before processing finishes, currentUserSession is overwritten return { session: currentUserSession }; }); ``` #### Production Standard (Correct) > **Standard**: State is bound exclusively to event.context for the duration of the request lifecycle, ensuring zero cross-tenant contamination. ```typescript // server/api/user-session.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserSessionContract } from '~~/shared/types/auth'; export default defineEventHandler((event): UserSessionContract => { // Request-scoped retrieval bound exclusively to the H3Event lifecycle const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } event.context.auth = { token: authHeader, accessedAt: Date.now() }; return { token: event.context.auth.token, accessedAt: event.context.auth.accessedAt }; }); ``` ### Shared Directory Cross-Import vs Isomorphic SSR State Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a standalone ref outside a composable shares that ref across all SSR requests, causing memory leaks and client-server hydration mismatch errors (DOM mismatch). ```typescript // app/composables/useTenantSettings.ts import { ref } from 'vue'; // ANTI-PATTERN: Leaks Node.js server dependencies or non-replicated client singletons into SSR const globalSettings = ref<{ theme: string } | null>(null); export const useTenantSettings = () => { if (!globalSettings.value) { // Non-deterministic hydration mismatch: Client and Server render different initial trees globalSettings.value = { theme: typeof window !== 'undefined' ? localStorage.getItem('theme') || 'light' : 'dark' }; } return { settings: globalSettings }; }; ``` #### Production Standard (Correct) > **Standard**: useState scopes state instantiation per SSR context and handles deterministic client payload hydration without leaking state or causing hydration mismatch bugs. ```typescript // app/composables/useTenantSettings.ts import { useState } from '#app'; import type { TenantSettings } from '~~/shared/types/tenant'; export const useTenantSettings = () => { // useState is SSR-isolated per request and serializes payload to window.__NUXT__ const settings = useState<TenantSettings>('tenant-settings', () => ({ theme: 'dark', locale: 'en-US' })); const updateTheme = (newTheme: 'light' | 'dark') => { settings.value.theme = newTheme; }; return { settings, updateTheme }; }; ```

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 isolation between Nuxt 4 client code in app/, Nitro v2 engine routes in server/, and universal utilities in shared/. Mandates per-request context isolation to eliminate multi-tenant cross-request state pollution and hydration mismatches during server-side rendering (SSR). 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 Direct Server Module Leakage into Client Hydration 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 Direct Server Module Leakage into Client Hydration	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 structure Nuxt 4 applications using the app/ folder for UI logic, server/ for Nitro routes and middleware, and shared/ exclusively for pure isomorphic utilities and contracts.

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.