Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration

--- description: Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration - Enforces strict architectural boundaries across Nuxt 4's app/, server/, and shared/ directories while preventing cross-request SSR state pollution. Mandates request-scoped context encapsulation in Nitro v2 event handlers and SSR-safe state management via useState to eliminate concurrent user data leakage. 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/nuxt4-nitro-shared-state-isolation-standard" --- # Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State in Nitro Handlers and Leaky SSR Composables ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro v2 production standards. You must mandate strict directory boundaries (app/, server/, shared/), zero cross-request state contamination in SSR, and proper context scoping in Nitro event handlers. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR state using Nuxt's `useState()` or Pinia stores created within setup/plugin scope, and NEVER declare reactive state (`ref`, `reactive`, or plain objects) in top-level module scope. - Engineers MUST NOT maintain mutable module-scoped variables within `server/api/`, `server/routes/`, or `server/middleware/`; all request state MUST be scoped to `event.context` or handled via idempotent per-request lifecycles. - The `shared/` directory MUST remain strictly isomorphic and runtime-agnostic, containing only pure utilities, schemas (e.g., Zod), and TypeScript types without Node.js primitives, browser APIs, or Vue reactivity imports. - Nitro server routes MUST consume request validation and serialization utilities defined in `shared/` to enforce unified contract validation between client and server layers. - Components and frontend composables inside `app/` MUST NEVER import directly from `server/`, and Nitro handlers inside `server/` MUST NEVER import from `app/`. ## Bad vs Good Implementations ### Nitro Handler & SSR Composable State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables in module scope within Nitro handlers causes cross-request state pollution, exposing sensitive data between concurrent users. Similarly, declaring Vue refs outside the composable factory in SSR environments shares reactive instances across multiple server requests. ```typescript // server/api/user.ts - CRITICAL: Module-level state shared across concurrent incoming requests let cachedSession: { userId: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { cachedSession = { userId: token.replace('Bearer ', '') }; } // Cross-request pollution: User B will receive User A's session during concurrent hits return { user: cachedSession }; }); // app/composables/useProfile.ts - CRITICAL: Global ref declared outside composable scope import { ref } from 'vue'; const globalProfile = ref<string | null>(null); // Leaks across SSR requests export const useProfile = () => { return { profile: globalProfile }; }; ``` #### Production Standard (Correct) > **Standard**: Shared types are cleanly partitioned in `shared/types/`. Nitro event processing is strictly scoped per request using `event.context`, avoiding shared Node memory bugs. Nuxt's `useState` ensures per-request state isolation during SSR and synchronizes properly during client hydration. ```typescript // shared/types/user.ts - Pure isomorphic contract export interface UserSession { userId: string; authenticatedAt: number; } // server/api/user.ts - Isolated Nitro v2 event context import type { UserSession } from '~~/shared/types/user'; export default defineEventHandler((event): { user: UserSession | null } => { const token = getHeader(event, 'authorization'); if (!token) { return { user: null }; } // State is purely scoped to H3Event context event.context.userSession = { userId: token.replace('Bearer ', ''), authenticatedAt: Date.now() } satisfies UserSession; return { user: event.context.userSession }; }); // app/composables/useProfile.ts - SSR-safe hydration via useState import type { UserSession } from '~~/shared/types/user'; export const useProfile = () => { // useState guarantees request isolation during SSR and proper hydration on the client const profile = useState<UserSession | null>('user-profile', () => null); return { profile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration

Nuxt 4 Nitro Isolation, Shared Directory Boundaries, and SSR State Hydration defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural boundaries across Nuxt 4's app/, server/, and shared/ directories while preventing cross-request SSR state pollution. Mandates request-scoped context encapsulation in Nitro v2 event handlers and SSR-safe state management via useState to eliminate concurrent user data leakage. 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 Leaky SSR Composables 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 Leaky SSR Composables	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 using Nuxt's `useState()` or Pinia stores created within setup/plugin scope, and NEVER declare reactive state (`ref`, `reactive`, or plain objects) in top-level module scope.

Engineers MUST ALWAYS isolate SSR state using Nuxt's `useState()` or Pinia stores created within setup/plugin scope, and NEVER declare reactive state (`ref`, `reactive`, or plain objects) in top-level module scope.

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.