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

--- description: Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation - Enforces strict architectural boundaries across Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state pollution in the Nitro v2 engine. Prohibits module-level mutable variables in server routes and mandates request-scoped context and isomorphic hydration primitives. 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-ssr-state-isolation" --- # Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Contamination in Nitro Handlers and Leaked Client State in Nuxt 4 Shared Directory ## System Constraints You are a Principal Software Architect enforcing industrial-grade standards for Nuxt 4 and Nitro v2. Mandate absolute isolation between the client-facing app/ directory, the Nitro server/ directory, and the isomorphic shared/ directory. Strictly prohibit mutable module-scoped singletons in server handlers and composables to eliminate multi-tenant cross-request memory leaks in SSR runtimes. ## Strict Guidelines - Engineers MUST ALWAYS enforce Nuxt 4 directory topology: UI components, pages, layouts, and Vue composables reside strictly under app/; server endpoints, storage drivers, and Nitro middleware reside strictly under server/; pure, side-effect-free isomorphic types and utilities reside strictly under shared/. - Engineers MUST NOT declare mutable module-level state (e.g., let session, const cache = new Map()) inside server/ routes or server/middleware. Nitro runs on long-lived event loops (Node.js/Workers) where module-level state persists across distinct HTTP requests, resulting in cross-tenant data leaks. - Engineers MUST ALWAYS use event.context in Nitro event handlers to store and propagate request-scoped metadata (such as authenticated user identities, traces, or database sessions). - Engineers MUST ALWAYS utilize useState() rather than raw Vue ref() or reactive() singletons at the file root in app/ composables to guarantee cross-request SSR state isolation and correct client payload hydration. - Code placed in shared/ MUST BE platform-agnostic, side-effect-free, and devoid of browser globals (window, document) or Node/Nitro server imports (h3, #nitro-internal). - Services MUST serialize complex domain state across the SSR boundary using definePayloadPlugin or definePayloadReducer when non-JSON primitives (e.g., Map, Set, custom classes) are hydrated from Nitro to the client. - Components NEVER directly import Nitro server handlers, server utilities, or internal server storage drivers. ## Bad vs Good Implementations ### Cross-Request State Leak in Nitro Route vs. Request-Scoped Event Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scoped variables in Nitro server routes persist across concurrent and subsequent HTTP requests in Node.js and Cloudflare Workers. One user's session data leaks to other incoming requests. ```typescript // server/api/profile.get.ts // FATAL: Module-scoped state shared across all concurrent requests in long-lived Nitro worker let currentUserCache: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, message: 'Unauthorized' }); } // Subsequent requests from different users will read the previous user's cached profile if (!currentUserCache) { currentUserCache = await resolveUserSession(token); } return { profile: currentUserCache }; }); ``` #### Production Standard (Correct) > **Standard**: The shared type contract is safely isolated in shared/types. Nitro handlers store transient request-level state exclusively in event.context, preventing cross-request memory contamination. ```typescript // shared/types/profile.ts // Pure isomorphic contract shared across app/ and server/ export interface UserProfile { id: string; role: string; } // server/api/profile.get.ts // Request-scoped safe execution using Nitro event context export default defineEventHandler(async (event): Promise<{ profile: UserProfile }> => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, message: 'Unauthorized' }); } // Securely bind state to the single request lifecycle via event.context if (!event.context.userProfile) { event.context.userProfile = await resolveUserSession(token); } return { profile: event.context.userProfile as UserProfile }; }); ``` ### Un-isolated Vue Composable vs. Nuxt 4 Hydrated SSR useState Composable #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring a Vue ref at the top-level of an app/ composable module causes the state to be shared across all SSR incoming requests on the server, causing hydration mismatch and security breaches. ```typescript // app/composables/useUser.ts import { ref } from 'vue'; // ANTI-PATTERN: Root-level ref is instantiated once per SSR node process // and leaks across different visitor SSR evaluations const globalUser = ref<{ id: string } | null>(null); export const useUser = () => { const setUser = (user: { id: string }) => { globalUser.value = user; }; return { globalUser, setUser }; }; ``` #### Production Standard (Correct) > **Standard**: useState scopes the state instance to the current active NuxtApp instance during SSR, serializes it automatically into the Nuxt hydration payload, and recovers it without hydration mismatch on the client. ```typescript // app/composables/useUser.ts import type { UserProfile } from '~~/shared/types/profile'; export const useUser = () => { // useState keys state uniquely per Nuxt SSR context and seamlessly serializes to client payload const user = useState<UserProfile | null>('user-state-key', () => null); const setUser = (newUser: UserProfile) => { user.value = newUser; }; return { user: readonly(user), setUser }; }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural boundaries across Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state pollution in the Nitro v2 engine. Prohibits module-level mutable variables in server routes and mandates request-scoped context and isomorphic hydration primitives. 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 Handlers and Leaked Client State in Nuxt 4 Shared Directory 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 Handlers and Leaked Client State in Nuxt 4 Shared Directory	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 enforce Nuxt 4 directory topology

Engineers MUST ALWAYS enforce Nuxt 4 directory topology: UI components, pages, layouts, and Vue composables reside strictly under app/; server endpoints, storage drivers, and Nitro middleware reside strictly under server/; pure, side-effect-free isomorphic types and utilities reside strictly under shared/.

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.