Nuxt 4 Directory Restructuring, Nitro Context & SSR State Isolation

--- description: Nuxt 4 Directory Restructuring, Nitro Context & SSR State Isolation - Enforces Nuxt 4 directory architecture (isolating application code inside `app/` and shared cross-runtime logic inside `shared/`), strict Nitro server-route context management, and per-request SSR state isolation. Prohibits global module-level mutable singletons and cross-boundary runtime contamination between Nitro server routes and Vue client 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/nuxt-4-nitro-shared-ssr-state-guardrail" --- # Nuxt 4 Directory Restructuring, Nitro Context & SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State Bleed and Invalid Directory Cross-Imports Across Nuxt 4 Runtimes ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro architectural invariants. Enforce strict adherence to the Nuxt 4 `app/` structure, `shared/` directory constraints, per-request event context isolation via `event.context`, and strict use of `useState` or per-request stores to prevent cross-request SSR state leaks. ## Strict Guidelines - Engineers MUST ALWAYS place client-side and Vue application components, composables, and pages within the root `app/` directory (or configure compatibilityVersion: 4). - Engineers MUST ALWAYS place universal utility functions, types, and DTO schemas inside `shared/` without importing runtime-specific dependencies (such as `h3`, `vue`, or DOM APIs). - Engineers MUST NOT declare global mutable variables or stateful module-level singletons in `server/` or `app/` as they cause memory leaks and cross-request SSR data bleeding. - Engineers MUST ALWAYS access and store per-request Nitro context exclusively through `event.context` using typed augmentations in `server/plugins` or middleware. - Engineers MUST ALWAYS wrap server-hydrated reactive state in `useState(key, init)` or dynamic per-request Pinia stores rather than standalone Vue `ref()` or `reactive()` outside setup lifecycle. - Components NEVER directly import modules from `server/` routes or Nitro utilities; communication must solely occur via type-safe `$fetch` or `useFetch` with Nitro runtime endpoints. - Nitro route handlers MUST ALWAYS return serializable plain JSON objects and use `defineEventHandler` or `defineLazyEventHandler` to maintain runtime boundaries. ## Bad vs Good Implementations ### Cross-Request State Leak in Nitro Route vs. Request-Scoped H3 Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Global mutable variables in Nitro handlers survive across requests in Node/Bun runtimes, leaking authenticated tenant identities across unrelated users. ```typescript // server/api/user.ts // ANTI-PATTERN: Global module-level state shared across concurrent requests let currentUser: { id: string; role: string } | null = null; export default defineEventHandler((event) => { const authHeader = getHeader(event, 'authorization'); if (authHeader) { currentUser = parseJwt(authHeader); // Leaks between tenant requests! } return { user: currentUser }; }); ``` #### Production Standard (Correct) > **Standard**: Attaching request-scoped data to `event.context` guarantees lifecycle isolation per request, preventing cross-tenant SSR memory pollution. ```typescript // server/api/user.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserSession } from '~~/shared/types/user'; declare module 'h3' { interface H3EventContext { user?: UserSession; } } export default defineEventHandler((event) => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, message: 'Unauthorized' }); } // Request-isolated context tied strictly to H3Event lifecycle event.context.user = parseJwt(authHeader); return { user: event.context.user }; }); ``` ### Nuxt 4 Shared Directory Hydration vs. Vue Client Root-Level ref() SSR Leak #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating a global `ref` at the top level of a composable file causes it to be shared across all SSR threads, rendering one client's data to another user during SSR. ```typescript // app/composables/useProfile.ts import { ref } from 'vue'; // ANTI-PATTERN: Global ref created outside setup or useState const globalProfile = ref<{ name: string } | null>(null); export const useProfile = () => { const setProfile = (name: string) => { globalProfile.value = { name }; }; return { profile: globalProfile, setProfile }; }; ``` #### Production Standard (Correct) > **Standard**: Nuxt's `useState` leverages Nuxt payload injection during SSR, serializing state per HTML request and safely restoring it on the client without thread cross-contamination. ```typescript // app/composables/useProfile.ts import { useState } from '#app'; import type { ProfileDTO } from '~~/shared/types/profile'; export const useProfile = () => { // Request-isolated hydration state keyed uniquely for SSR de-duplication const profile = useState<ProfileDTO | null>('user-profile-key', () => null); const setProfile = (data: ProfileDTO) => { profile.value = data; }; return { profile, setProfile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Restructuring, Nitro Context & SSR State Isolation

Nuxt 4 Directory Restructuring, Nitro Context & SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces Nuxt 4 directory architecture (isolating application code inside `app/` and shared cross-runtime logic inside `shared/`), strict Nitro server-route context management, and per-request SSR state isolation. Prohibits global module-level mutable singletons and cross-boundary runtime contamination between Nitro server routes and Vue client 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-Level State Bleed and Invalid Directory Cross-Imports Across Nuxt 4 Runtimes 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 and Invalid Directory Cross-Imports Across Nuxt 4 Runtimes	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 and Vue application components, composables, and pages within the root `app/` directory (or configure compatibilityVersion

Engineers MUST ALWAYS place client-side and Vue application components, composables, and pages within the root `app/` directory (or configure compatibilityVersion: 4).

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.