Nuxt 4 Nitro Engine Boundaries, Shared Directory Invariants, and SSR State Isolation

--- description: Nuxt 4 Nitro Engine Boundaries, Shared Directory Invariants, and SSR State Isolation - Mandates strict architectural boundaries between Nuxt 4's `app/` presentation layer, Nitro `server/` runtime, and the universal `shared/` directory. Enforces request-scoped state encapsulation using `useState()` and `H3Event` context to prevent cross-request memory contamination and SSR hydration mismatches. 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-engine-shared-state-isolation" --- # Nuxt 4 Nitro Engine Boundaries, Shared Directory Invariants, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State Bleed in Nitro Handlers and Direct Client-Server Cross-Boundary Imports ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural constraints and Nitro runtime invariants. In Nuxt 4, application code resides strictly in `app/`, backend code in `server/`, and pure universal domain logic in `shared/`. You must strictly prevent cross-boundary imports between `app/` and `server/`, eliminate module-scoped state in Nitro handlers that causes state leakage across concurrent SSR requests, and enforce atomic SSR-to-client hydration with `useState()`. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR state per request using `useState<T>()` in the `app/` layer or `event.context` in Nitro handlers; module-level mutable variables (`let`, `const cache = new Map()`, `ref()`) outside of request scopes are strictly prohibited. - Engineers MUST NOT import server-only code (e.g., `#imports` referencing server utilities, Node.js built-ins, DB clients, Nitro handlers) into the `app/` directory, nor import Vue/browser-specific APIs into `server/`. - Code placed in the `shared/` directory MUST remain purely isomorphic and free of runtime side effects, depending neither on Nitro runtime primitives (`H3Event`, `defineEventHandler`) nor Vue composition APIs (`ref`, `computed`, `onMounted`). - Services in `server/` MUST access request-specific configurations and credentials exclusively via `useRuntimeConfig(event)` or `event.context`, never reading directly from unvalidated global `process.env` during request handling. - Components NEVER initialize reactive state that depends on server-only data without resolving through `useAsyncData` or `useFetch` to prevent SSR serialization mismatches and hydration failure. ## Bad vs Good Implementations ### Cross-Request State Contamination in Nitro Server Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`activeUserSession`) at the module scope in Nitro persists across requests within the persistent Node/V8 isolate. This causes severe security breaches by exposing one user's authenticated context to another concurrent request. ```typescript // server/api/user/session.ts import { defineEventHandler } from 'h3'; // CRITICAL FLAW: Module-scoped state shared across concurrent requests let activeUserSession: { userId: string; token: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { activeUserSession = await validateToken(token); } // Leaks previous request's session to concurrent unauthenticated requests return { user: activeUserSession }; }); ``` #### Production Standard (Correct) > **Standard**: State is scoped explicitly to the single request lifecycle using local execution frames and `event.context`. Shared contracts are safely consumed from the universal `shared/types/auth` directory. ```typescript // server/api/user/session.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserSession } from '~~/shared/types/auth'; export default defineEventHandler(async (event): Promise<{ user: UserSession }> => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // SAFE: Bound strictly to the current H3Event lifecycle const session = await validateToken(token); event.context.user = session; return { user: session }; }); ``` ### Universal Directory Boundary Violation and Unsafe SSR Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly importing from `server/` leaks server infrastructure and secrets into client bundles. Using a module-level `ref` inside a composable leaks user data across requests during SSR rendering. ```typescript // app/composables/useProfile.ts import { ref } from 'vue'; // CRITICAL FLAW: Importing server-side DB client and state directly into client-side code import { db } from '../../server/utils/db'; // CRITICAL FLAW: Global ref bleeds across SSR renders on the server const globalProfile = ref(null); export const useProfile = () => { const fetchProfile = async (id: string) => { globalProfile.value = await db.user.findUnique({ where: { id } }); }; return { profile: globalProfile, fetchProfile }; }; ``` #### Production Standard (Correct) > **Standard**: Uses `useState()` with a unique key to scope hydration per request, communicates with `server/` via standard HTTP endpoints using `useFetch()`, and imports shared definitions strictly from `shared/`. ```typescript // app/composables/useProfile.ts import type { UserProfile } from '~~/shared/types/user'; export const useProfile = (id: MaybeRefOrGetter<string>) => { // SAFE: useState provides unique SSR request isolation and automatic hydration serialization const profile = useState<UserProfile | null>(`profile-${toValue(id)}`, () => null); const { data, status, error, refresh } = useFetch<UserProfile>(() => `/api/profile/${toValue(id)}`, { key: `fetch-profile-${toValue(id)}`, default: () => profile.value }); return { profile: data, status, error, refresh }; }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine Boundaries, Shared Directory Invariants, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Mandates strict architectural boundaries between Nuxt 4's `app/` presentation layer, Nitro `server/` runtime, and the universal `shared/` directory. Enforces request-scoped state encapsulation using `useState()` and `H3Event` context to prevent cross-request memory contamination and SSR hydration mismatches. 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 Bleed in Nitro Handlers and Direct Client-Server Cross-Boundary 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	Global Module-Level State Bleed in Nitro Handlers and Direct Client-Server Cross-Boundary 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 state per request using `useState<T>()` in the `app/` layer or `event.context` in Nitro handlers

Engineers MUST ALWAYS isolate SSR state per request using `useState<T>()` in the `app/` layer or `event.context` in Nitro handlers; module-level mutable variables (`let`, `const cache = new Map()`, `ref()`) outside of request scopes are strictly prohibited.

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.