Nuxt 4 Directory Restructuring, Nitro Route Handlers, and SSR State Isolation

--- description: Nuxt 4 Directory Restructuring, Nitro Route Handlers, and SSR State Isolation - Nuxt 4 transitions all client application code into the app/ directory while Nitro server execution operates strictly under server/ and cross-runtime shared logic resides in shared/. Direct state mutation across runtime boundaries or module-level shared variables in Nitro handlers leads to cross-request state leakage, memory leaks, 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-shared-directory-ssr-isolation-standard" --- # Nuxt 4 Directory Restructuring, Nitro Route Handlers, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Contamination via Global Nitro State and Legacy Root Directory Imports in Nuxt 4 ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architecture and Nitro engine safety invariants. Enforce strict isolation between app/, server/, and shared/ directories, mandate event-scoped Nitro execution context, prevent global singletons in Nitro handlers to eliminate cross-request state pollution, and guarantee deterministic SSR hydration. ## Strict Guidelines - Engineers MUST ALWAYS organize Nuxt 4 application code under the app/ folder (e.g., app/components, app/composables, app/pages) unless backward compatibility mode is explicitly declared in nuxt.config.ts. - Engineers MUST use the shared/ directory exclusively for runtime-agnostic utilities, universal validation schemas (e.g., Zod, Valibot), and pure type definitions shared between app/ and server/. - Engineers MUST NOT declare mutable variables outside the event handler scope in server/ routes or middleware, as Nitro operates as a persistent Node.js/worker process where module-level scope is shared across concurrent requests. - Services MUST attach request-scoped state exclusively to H3Event context via event.context or resolve state inside defineEventHandler using event-scoped factories. - Components NEVER use module-level reactive references (e.g., const state = ref()) outside of useNuxtApp() or useState() hooks, as this leaks user data across SSR sessions. - Engineers MUST use useState() with a unique deterministic key for any SSR-to-client transferred state rather than raw Vue ref() or reactive() primitives initialized during setup. ## Bad vs Good Implementations ### Nitro Server Route State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'activeCart' at the module level in a Nitro route causes state leakage between distinct HTTP requests, as Nitro does not re-initialize module closures per request. Cart items from User A are exposed to User B. ```typescript // server/api/cart.ts import { defineEventHandler, readBody } from 'h3'; // CRITICAL BUG: Module-scoped state shared across all concurrent user requests! const activeCart: string[] = []; export default defineEventHandler(async (event) => { const body = await readBody<{ item: string }>(event); activeCart.push(body.item); return { items: activeCart }; }); ``` #### Production Standard (Correct) > **Standard**: Request-specific dependencies and data are accessed per-event via storage drivers and authenticated user contexts, preventing cross-request pollution. ```typescript // server/api/cart.ts import { defineEventHandler, readBody, createError } from 'h3'; import { cartItemSchema } from '~~/shared/utils/schemas'; export default defineEventHandler(async (event) => { const userId = event.context.auth?.userId; if (!userId) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } const rawBody = await readBody(event); const parsed = cartItemSchema.safeParse(rawBody); if (!parsed.success) { throw createError({ statusCode: 400, statusMessage: 'Invalid payload' }); } // Scoped to the current request execution context / persistent store const cartStorage = useStorage('redis'); const key = `user:${userId}:cart`; const existing = (await cartStorage.getItem<string[]>(key)) ?? []; const updated = [...existing, parsed.data.item]; await cartStorage.setItem(key, updated); return { items: updated }; }); ``` ### Nuxt 4 Client Hydration State vs Module Singleton #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defining a Vue ref outside of the composable function creates a persistent singleton across requests on the SSR server, leaking user profile data across distinct incoming visitor connections. ```typescript // app/composables/useProfile.ts import { ref } from 'vue'; // CRITICAL BUG: Shared singleton across SSR requests in Node runtime const globalProfile = ref<{ name: string } | null>(null); export const useProfile = () => { const fetchProfile = async () => { const { data } = await useFetch('/api/profile'); globalProfile.value = data.value; }; return { profile: globalProfile, fetchProfile }; }; ``` #### Production Standard (Correct) > **Standard**: useState scopes the reactive state to the current Nuxt instance (useNuxtApp().payload.state), guaranteeing strict multi-tenant SSR memory safety and serializing data accurately to prevent hydration mismatches. ```typescript // app/composables/useProfile.ts import type { UserProfile } from '~~/shared/types'; export const useProfile = () => { // useState guarantees per-request isolation on server and hydration bridge to client const profile = useState<UserProfile | null>('user-profile-state', () => null); const fetchProfile = async () => { const { data, error } = await useFetch<UserProfile>('/api/profile'); if (error.value) { throw createError({ ...error.value, fatal: false }); } if (data.value) { profile.value = data.value; } }; return { profile: readonly(profile), fetchProfile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Restructuring, Nitro Route Handlers, and SSR State Isolation

Nuxt 4 Directory Restructuring, Nitro Route Handlers, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 transitions all client application code into the app/ directory while Nitro server execution operates strictly under server/ and cross-runtime shared logic resides in shared/. Direct state mutation across runtime boundaries or module-level shared variables in Nitro handlers leads to cross-request state leakage, memory leaks, 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: Cross-Request State Contamination via Global Nitro State and Legacy Root Directory Imports in Nuxt 4 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	Cross-Request State Contamination via Global Nitro State and Legacy Root Directory Imports in Nuxt 4	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 organize Nuxt 4 application code under the app/ folder (e.g., app/components, app/composables, app/pages) unless backward compatibility mode is explicitly declared in nuxt.config.ts.

Engineers MUST ALWAYS organize Nuxt 4 application code under the app/ folder (e.g., app/components, app/composables, app/pages) unless backward compatibility mode is explicitly declared in nuxt.config.ts.

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.