Nuxt 4 App Restructuring, Nitro Isolation, and Hydration Invariant

--- description: Nuxt 4 App Restructuring, Nitro Isolation, and Hydration Invariant - Enforces strict isolation between Nuxt 4's app/ directory structure, the shared/ directory, and Nitro server execution contexts. Prevents cross-request SSR state leakage via module-scope singletons and ensures clean contracts for Nitro event handlers and isomorphic code. 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-directory-guardrail" --- # Nuxt 4 App Restructuring, Nitro Isolation, and Hydration Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module Singletons Leaking Cross-Request SSR State & Boundary Violations Across Nuxt 4 Shared/App Directories ## System Constraints You are a Principal Software Architect enforcing production standards for Nuxt 4 applications. You must ensure adherence to the Nuxt 4 directory structure (app/, server/, shared/), prevent cross-request state pollution in Nitro and SSR Vue runtimes, and enforce strictly typed, isolated boundaries between client and server layers. ## Strict Guidelines - Engineers MUST ALWAYS place client-side UI code, composables, components, and pages inside the `app/` directory according to Nuxt 4 standards. - Engineers MUST NEVER maintain stateful singletons or mutable variables in the module root scope of Nitro handlers, plugins, or shared composables during SSR. - Engineers MUST use the `shared/` directory solely for stateless utilities, pure domain types, and deterministic validation schemas consumed by both `app/` and `server/`. - Engineers MUST NEVER import browser-exclusive APIs (window, document, localStorage) inside `shared/` or `server/` files without conditional execution boundaries. - Components and composables MUST manage reactive SSR state exclusively through `useState()` or scoped Pinia stores initialized per-request to avoid memory leaks and data bleed across distinct client requests. - Nitro server event handlers MUST always wrap execution contexts within `defineEventHandler` and retrieve request-specific state strictly from `event.context`. ## Bad vs Good Implementations ### SSR Cross-Request State Leakage vs. Request-Scoped Reactive Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `ref` at the module root outside a composable causes it to be retained by the Node.js/Nitro execution process across multiple client requests during SSR, resulting in catastrophic cross-tenant data leaks. ```typescript // app/composables/useUserSession.ts import { ref } from 'vue'; // CRITICAL BUG: Module-scoped reactive singleton shared across concurrent SSR requests const userProfile = ref<UserProfile | null>(null); export const useUserSession = () => { const setProfile = (profile: UserProfile) => { userProfile.value = profile; }; return { userProfile, setProfile }; }; ``` #### Production Standard (Correct) > **Standard**: `useState` ties the state key directly to the active `nuxtApp` context, ensuring that state is isolated per HTTP request during SSR and correctly serialized for hydration on the client. ```typescript // app/composables/useUserSession.ts import type { UserProfile } from '~~/shared/types/user'; export const useUserSession = () => { // Request-isolated SSR-safe state bound to the current Nuxt instance const userProfile = useState<UserProfile | null>('user-profile-session', () => null); const setProfile = (profile: UserProfile) => { userProfile.value = profile; }; return { userProfile, setProfile }; }; ``` ### Nitro Server Handler with Leaky Module State vs. Context Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Persistent state in the module scope of a Nitro handler persists indefinitely in the running worker instance, allowing concurrent users to overwrite and read each other's data payloads. ```typescript // server/api/cart.ts import { defineEventHandler, readBody } from 'h3'; // CRITICAL BUG: Module-level cache leaks across separate incoming requests const requestCache = new Map<string, any>(); export default defineEventHandler(async (event) => { const body = await readBody(event); requestCache.set('lastPayload', body); return { status: 'processed', cached: requestCache.get('lastPayload') }; }); ``` #### Production Standard (Correct) > **Standard**: Nitro's `event.context` exists exclusively for the lifecycle of that specific HTTP request, guaranteeing complete concurrency safety across worker processes. ```typescript // server/api/cart.ts import { defineEventHandler, readBody } from 'h3'; import { CartPayloadSchema } from '~~/shared/schemas/cart'; export default defineEventHandler(async (event) => { const rawBody = await readBody(event); const payload = CartPayloadSchema.parse(rawBody); // Ephemeral per-request storage isolated via event.context event.context.cart = payload; return { status: 'processed', cart: event.context.cart }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 App Restructuring, Nitro Isolation, and Hydration Invariant

Nuxt 4 App Restructuring, Nitro Isolation, and Hydration Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between Nuxt 4's app/ directory structure, the shared/ directory, and Nitro server execution contexts. Prevents cross-request SSR state leakage via module-scope singletons and ensures clean contracts for Nitro event handlers and isomorphic code. 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 Singletons Leaking Cross-Request SSR State & Boundary Violations Across Nuxt 4 Shared/App Directories 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 Singletons Leaking Cross-Request SSR State & Boundary Violations Across Nuxt 4 Shared/App Directories	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 place client-side UI code, composables, components, and pages inside the `app/` directory according to Nuxt 4 standards.

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.