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

--- description: Nuxt 4 Nitro Engine, Shared Directory Boundaries, and SSR State Isolation - Enforces strict boundary isolation across Nuxt 4's app/, server/, and shared/ directories, preventing cross-request state contamination in Nitro server handlers and ensuring deterministic SSR hydration. Prohibits global mutable singletons across concurrent execution contexts and mandates serializable data transfer boundaries. 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-state-isolation-guardrail" --- # Nuxt 4 Nitro Engine, Shared Directory Boundaries, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Level Mutable State in Server Routes and Shared Modules Leaking Cross-Request Tenant Data ## System Constraints You are a Principal Software Architect enforcing strict Nuxt 4 architecture and Nitro v2 isolation rules. Nuxt 4 introduces a restructured directory layout (app/, server/, shared/) and optimized Nitro server pipelines. You must prevent cross-request state pollution (CRSP) in server runtimes, enforce strict serializability for SSR-to-client hydration transfer, and block illegal cross-layer imports. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-scoped state within Nitro event handlers using `event.context` rather than module-scoped top-level variables. - Engineers MUST NOT declare mutable singletons, module-level variables (e.g., `let currentUser`), or in-memory caches in `server/` or `shared/` code. - Code placed in `shared/` MUST be strictly isomorphic, side-effect-free, and limited to pure utility functions, TypeScript interfaces, and validation schemas (e.g., Zod, Valibot). - Code in `app/` MUST NEVER import server-only utilities or Nitro dependencies (`h3`, `#imports` pointing to server-only tools), and `server/` MUST NOT import client components or Vue composables. - Nitro handlers MUST return JSON-serializable plain objects; passing non-serializable instances (Date objects, class instances with prototypes, functions, circular structures) without custom transformers across the SSR hydration boundary is prohibited. - Engineers MUST wrap SSR-shared state in `useState(key, init)` with unique hydration keys instead of native Vue `ref()` or `reactive()` singletons defined outside setup functions. ## Bad vs Good Implementations ### Cross-Request State Contamination in Nitro Server Route Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `activeUserSession` at the module root causes state leakage across concurrent HTTP requests in long-running Node.js processes or warm serverless containers. One user's profile can be returned to another tenant. ```typescript // server/api/user/session.ts import { defineEventHandler } from 'h3'; // CRITICAL SECURITY BUG: Module-scoped variable persists across concurrent SSR requests in Node/Worker pools let activeUserSession: { userId: string; roles: string[] } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { activeUserSession = await verifyAndLoadUser(token); } // Leaks previous request's identity to subsequent unauthenticated requests return { user: activeUserSession }; }); ``` #### Production Standard (Correct) > **Standard**: State is bound exclusively to the invocation's `H3Event` context (`event.context`), guaranteeing total isolation between concurrent requests without memory leakage. ```typescript // server/api/user/session.ts import { defineEventHandler, getHeader, createError } from 'h3'; interface UserSession { userId: string; roles: string[]; } export default defineEventHandler(async (event): Promise<{ user: UserSession | null }> => { const token = getHeader(event, 'authorization'); if (!token) { return { user: null }; } // Request-scoped storage via Nitro event context if (!event.context.userSession) { const session = await verifyAndLoadUser(token); if (!session) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } event.context.userSession = session; } return { user: event.context.userSession as UserSession }; }); ``` ### Hydration State Serialization and Nuxt 4 Shared Contract #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly importing from `server/` into `app/` violates architecture boundaries, leaking server logic to client bundles. Declaring `ref` outside the composable creates a persistent SSR singleton, and class instances fail hydration serialization. ```typescript // app/composables/useUserProfile.ts import { ref } from 'vue'; import { UserModel } from '~/server/utils/models'; // ILLEGAL: Client importing server implementation // Global singleton in client bundle causes cross-request contamination in SSR const userState = ref<UserModel | null>(null); export const useUserProfile = () => { const fetchUser = async () => { // Class instance with methods does not serialize cleanly across SSR boundary const data = await $fetch('/api/user/session'); userState.value = new UserModel(data.user); }; return { userState, fetchUser }; }; ``` #### Production Standard (Correct) > **Standard**: Interfaces are stored in Nuxt 4's `shared/` layer. `useState()` guarantees safe cross-request isolation during SSR and clean payload de-serialization on the client. ```typescript // shared/types/user.ts export interface UserDTO { readonly id: string; readonly email: string; readonly roles: readonly string[]; } // app/composables/useUserProfile.ts import type { UserDTO } from '~~/shared/types/user'; export const useUserProfile = () => { // Nuxt-managed, SSR-safe, request-isolated reactive state const user = useState<UserDTO | null>('user-profile-session', () => null); const fetchUser = async () => { const { data, error } = await useFetch<{ user: UserDTO | null }>('/api/user/session'); if (!error.value && data.value) { user.value = data.value.user; } }; return { user: readonly(user), fetchUser }; }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine, Shared Directory Boundaries, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation across Nuxt 4's app/, server/, and shared/ directories, preventing cross-request state contamination in Nitro server handlers and ensuring deterministic SSR hydration. Prohibits global mutable singletons across concurrent execution contexts and mandates serializable data transfer boundaries. 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: Module-Level Mutable State in Server Routes and Shared Modules Leaking Cross-Request Tenant Data 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	Module-Level Mutable State in Server Routes and Shared Modules Leaking Cross-Request Tenant Data	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 request-scoped state within Nitro event handlers using `event.context` rather than module-scoped top-level variables.

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.