Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Leak Prevention

--- description: Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Leak Prevention - Nuxt 4 introduces a restructured directory hierarchy where application code resides inside `app/` and shared cross-boundary utilities live in `shared/`. Nitro server runtime context must remain strictly isolated from Vue client runtimes, prohibiting global mutable module state in Nitro event handlers and ensuring SSR hydration payloads use serializable `useState` rather than top-level variables. 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/nuxt-4-nitro-shared-directory-ssr-isolation-guardrail" --- # Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Leak Prevention > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Contamination in Nitro and Leaking Server Singletons into Client Hydration ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural migration, Nitro v2 execution isolation, and zero cross-request SSR state leakages. Nuxt 4 mandates strict physical directory partitioning: root-level app code moves into `app/`, reusable isomorphic logic resides in `shared/`, and server logic lives under `server/`. You must strictly reject any top-level mutable state in Nitro routes, block direct Node.js/Nitro internal imports from `app/`, enforce context-scoped event handling via `H3Event`, and ensure state hydration exclusively uses Nuxt's `useState` composable with deterministic serialization. ## Strict Guidelines - Engineers MUST ALWAYS organize frontend application code within the `app/` directory (e.g., `app/components/`, `app/composables/`, `app/pages/`) adhering to Nuxt 4 standard topology. - Engineers MUST place universal utilities, constants, and pure TypeScript types inside the root `shared/` directory, imported using the `~shared` or `#shared` alias. - Engineers MUST NOT declare mutable module-level variables (e.g., `let cache = {}`, `let currentUser`) in Nitro event handlers or server middleware; all per-request state must attach to `event.context`. - Components and composables MUST NEVER instantiate non-isolated global reactive refs outside of `useState` or setup functions during SSR, as this causes multi-tenant data leaks across concurrent requests. - Nitro server routes MUST return strictly JSON-serializable payloads or instances of `H3Response`/`sendWebResponse`; functions, circular structures, and raw class instances with prototype chains are prohibited. - Engineers MUST NOT import Nitro server internals, database clients, or Node.js server built-ins (`fs`, `net`, `crypto` direct server bindings) into files located under `app/` or `shared/`. - Hydration state across server and client boundaries MUST be initialized via `useState('uniqueKey', () => initialValue)` to guarantee idempotent state reproduction on the client. ## Bad vs Good Implementations ### Cross-Request State Pollution in Nitro Server Handler vs Context Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-level variables in Nitro server handlers persist across concurrent HTTP requests on the same runtime process/worker. Storing request-specific context like tenant IDs or user sessions in top-level variables causes critical cross-tenant data leaks under concurrency. ```typescript // server/api/user/session.ts - ANTI-PATTERN: Shared module-level mutable state let currentTenantId: string | null = null; export default defineEventHandler(async (event) => { const tenantHeader = getHeader(event, 'x-tenant-id'); if (tenantHeader) { currentTenantId = tenantHeader; // Leaks across concurrent requests! } // Race condition: another request can mutate currentTenantId before resolve const data = await fetchTenantData(currentTenantId); return { tenantId: currentTenantId, data }; }); ``` #### Production Standard (Correct) > **Standard**: Per-request state is explicitly bound to `event.context`, ensuring strictly isolated lifecycle boundaries. H3Event types are augmented for compile-time verification, eliminating multi-tenant cross-contamination. ```typescript // server/api/user/session.ts - PRODUCTION-GRADE: Request-scoped H3 event context import { fetchTenantData } from '#imports'; import type { TenantContext } from '~~/shared/types/tenant'; declare module 'h3' { interface H3EventContext { tenant?: TenantContext; } } export default defineEventHandler(async (event) => { const tenantHeader = getHeader(event, 'x-tenant-id'); if (!tenantHeader) { throw createError({ statusCode: 400, statusMessage: 'Missing x-tenant-id header' }); } event.context.tenant = { id: tenantHeader, timestamp: Date.now() }; const data = await fetchTenantData(event.context.tenant.id); return { tenantId: event.context.tenant.id, data }; }); ``` ### Un-isolated SSR State Hydration vs Nuxt 4 `useState` and `shared/` Schema #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring a `ref` outside of a composable function creates a server-wide singleton. In SSR, this ref is shared across all incoming user requests, exposing User A's profile data to User B and breaking client-side hydration matching. ```typescript // app/composables/useProfile.ts - ANTI-PATTERN: Shared ref singleton leaking SSR state import { ref } from 'vue'; // Module-scope ref shared across all SSR server requests const globalProfile = ref<{ id: string; name: string } | null>(null); export const useProfile = () => { const setProfile = (profile: { id: string; name: string }) => { globalProfile.value = profile; }; return { profile: globalProfile, setProfile }; }; ``` #### Production Standard (Correct) > **Standard**: Using `useState` registers state within Nuxt's per-request SSR payload payload (`nuxtApp.payload.state`), ensuring total memory isolation across requests and transparent, tamper-proof hydration transfers to the client. ```typescript // app/composables/useProfile.ts - PRODUCTION-GRADE: Isolated SSR Hydration with Shared Contract import type { UserProfile } from '~~/shared/types/user'; export const useProfile = () => { // useState binds state to current Nuxt SSR context instance, serialized safely to __NUXT_DATA__ const profile = useState<UserProfile | null>('user-profile-session', () => null); const setProfile = (data: UserProfile) => { profile.value = data; }; const clearProfile = () => { profile.value = null; }; return { profile: readonly(profile), setProfile, clearProfile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Leak Prevention

Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Leak Prevention defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 introduces a restructured directory hierarchy where application code resides inside `app/` and shared cross-boundary utilities live in `shared/`. Nitro server runtime context must remain strictly isolated from Vue client runtimes, prohibiting global mutable module state in Nitro event handlers and ensuring SSR hydration payloads use serializable `useState` rather than top-level variables. 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 in Nitro and Leaking Server Singletons into Client Hydration 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 in Nitro and Leaking Server Singletons into Client Hydration	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 frontend application code within the `app/` directory (e.g., `app/components/`, `app/composables/`, `app/pages/`) adhering to Nuxt 4 standard topology.

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.