Nuxt 4 Nitro Server Architecture & Shared Directory Hydration Guardrail

--- description: Nuxt 4 Nitro Server Architecture & Shared Directory Hydration Guardrail - Enforces strict isolation across the Nuxt 4 directory topology (`app/`, `server/`, and `shared/`) to prevent SSR cross-request state pollution, Nitro runtime memory leaks, and hydration mismatches. Restricts the `shared/` directory to pure isomorphic code free from client- or server-specific side effects, and bans module-scoped mutable state in Nitro handlers and Vue composables. globs: app/**/*.{ts,js,vue}, server/**/*.{ts,js}, shared/**/*.{ts,js}, nuxt.config.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt4-nitro-shared-directory-isolation-production-standard" --- # Nuxt 4 Nitro Server Architecture & Shared Directory Hydration Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Cross-Request Tenant State via Nitro Module Globals and Impure Shared Imports ## System Constraints You are a Principal Software Architect enforcing production safety in Nuxt 4 applications. You must enforce strict architectural boundaries between `app/`, `server/`, and `shared/` directories. Prevent cross-request state leaks, module-level global variables in Nitro server routes, invalid import directionality, and SSR hydration mismatches caused by un-keyed or module-scoped state. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR client state using `useState<T>('unique-key', () => init)` inside `app/composables` and NEVER declare mutable `ref()`, `reactive()`, or primitive variables at the module root level. - Engineers MUST NOT maintain mutable in-memory variables (such as `let userSession`, global `Map`, or arrays) at the module top level in `server/` routes, as Node.js and Nitro runtimes retain module state across concurrent multi-tenant requests. - Engineers MUST ALWAYS store per-request Nitro context exclusively within `event.context` using typed H3 middleware or define explicit caching via `defineCachedEventHandler` and Nitro's Unstorage engine. - Services MUST keep `shared/` strictly isomorphic; files in `shared/` MUST NOT import server-only primitives (`h3`, `node:*`, Nitro virtual imports) or client-only primitives (`vue`, `vue-router`, DOM APIs, or browser globals). - Components NEVER import directly from `server/` directories, and Nitro server handlers NEVER import components, composables, or client logic from `app/`. - Code SHOULD enforce strict type-safe schemas (e.g., Zod, Valibot) within `shared/utils` or `shared/types` to allow identical payload validation on both Nitro ingress endpoints and client form submissions. ## Bad vs Good Implementations ### Nitro Server Route State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scoped variables like `currentTenantId` and `memoryCache` remain allocated in the runtime process across multiple concurrent user requests. In an SSR/Nitro environment, concurrent requests will overwrite `currentTenantId`, leaking private tenant data across different users and causing race conditions. ```typescript // server/api/user/session.ts - ANTI-PATTERN: Module-level mutable state leaks across requests import { defineEventHandler, getQuery } from 'h3'; let currentTenantId: string | null = null; const memoryCache = new Map<string, any>(); export default defineEventHandler(async (event) => { const query = getQuery(event); // Concurrency bug: overwriting global variable leaks tenant data across concurrent HTTP requests currentTenantId = query.tenantId as string; if (memoryCache.has(currentTenantId)) { return memoryCache.get(currentTenantId); } const data = await fetchTenantData(currentTenantId); memoryCache.set(currentTenantId, data); return data; }); ``` #### Production Standard (Correct) > **Standard**: The fix eliminates all module-level mutable variables. Request-scoped parameters are retained in the execution scope and bound to `event.context`. Shared cross-request data uses Nitro's configured `useStorage()` interface with deterministic keys and TTLs. ```typescript // server/api/user/session.ts - PRODUCTION FIX: Scoped to H3Event context and Unstorage import { defineEventHandler, getQuery, createError } from 'h3'; export default defineEventHandler(async (event) => { const query = getQuery(event); const tenantId = query.tenantId as string; if (!tenantId) { throw createError({ statusCode: 400, statusMessage: 'Missing tenantId' }); } // Store transient request data safely inside event.context event.context.tenantId = tenantId; // Leverage Nitro's built-in multi-driver Unstorage cache const storage = useStorage('cache'); const cacheKey = `tenants:${tenantId}`; const cached = await storage.getItem(cacheKey); if (cached) { return cached; } const data = await fetchTenantData(tenantId); await storage.setItem(cacheKey, data, { ttl: 60 }); return data; }); ``` ### Isomorphic Shared Utilities vs SSR Vue State #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `shared/` must be pure and runtime-agnostic. Importing `vue` into `shared/` causes Nitro builds to bundle Vue runtime dependencies unnecessarily. Furthermore, exporting a module-level `ref` causes SSR state leakage where one user's profile is hydrated into another user's HTML payload. ```typescript // shared/utils/auth.ts - ANTI-PATTERN: Vue reactive state inside shared/ directory import { ref } from 'vue'; // Banned: Vue runtime dependency in isomorphic shared/ // Module-level ref causes memory leaks and cross-request state pollution during SSR export const globalUserProfile = ref<any>(null); export function useSetProfile(profile: any) { globalUserProfile.value = profile; } ``` #### Production Standard (Correct) > **Standard**: Contract types and pure logic are isolated within `shared/types/` without external UI framework dependencies. SSR-safe state hydration is exclusively declared within `app/composables/` using Nuxt's unique-keyed `useState()` primitive. ```typescript // shared/types/auth.ts - PRODUCTION FIX: Pure contract in shared/ export interface UserProfile { id: string; tenantId: string; roles: string[]; } // app/composables/useAuthProfile.ts - Nuxt 4 SSR-safe hydration state export const useAuthProfile = () => { // useState is scoped per SSR request context and automatically hydrated to the client return useState<UserProfile | null>('auth-profile-state', () => null); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Architecture & Shared Directory Hydration Guardrail

Nuxt 4 Nitro Server Architecture & Shared Directory Hydration Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation across the Nuxt 4 directory topology (`app/`, `server/`, and `shared/`) to prevent SSR cross-request state pollution, Nitro runtime memory leaks, and hydration mismatches. Restricts the `shared/` directory to pure isomorphic code free from client- or server-specific side effects, and bans module-scoped mutable state in Nitro handlers and Vue composables. 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 Cross-Request Tenant State via Nitro Module Globals and Impure Shared Imports 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 Cross-Request Tenant State via Nitro Module Globals and Impure Shared Imports	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 client state using `useState<T>('unique-key', () => init)` inside `app/composables` and NEVER declare mutable `ref()`, `reactive()`, or primitive variables at the module root level.

Engineers MUST ALWAYS isolate SSR client state using `useState<T>('unique-key', () => init)` inside `app/composables` and NEVER declare mutable `ref()`, `reactive()`, or primitive variables at the module root level.

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.