Nuxt 4 Nitro Server Isolation, App Reorganization, and SSR Hydration Standard

--- description: Nuxt 4 Nitro Server Isolation, App Reorganization, and SSR Hydration Standard - Enforces strict boundary separation between Nuxt 4 app/ runtime, Nitro server engine, and shared/ utilities. Prohibits global state pollution across concurrent SSR requests and eliminates cross-boundary imports between server and client domains. 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-ssr-isolation-guardrail" --- # Nuxt 4 Nitro Server Isolation, App Reorganization, and SSR Hydration Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Node Module State Leaks Across SSR Requests and Cross-Boundary Nitro Module Imports ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architecture and Nitro server invariants. Mandate strict directory isolation between app/, server/, and shared/. Enforce request-scoped SSR state isolation to eliminate memory leaks and multi-tenant cross-talk. Prohibit server-only logic inside Vue components and prevent client-side bundle pollution from Nitro handlers. ## Strict Guidelines - Engineers MUST ALWAYS organize Nuxt 4 frontend code within the app/ directory, backend Nitro logic within server/, and isomorphic primitives inside shared/. - Engineers MUST NEVER declare mutable state in module scope within Nitro server routes or composables, as this state persists across concurrent SSR requests causing data leaks. - Engineers MUST ALWAYS encapsulate SSR state within Nuxt's useState() or Pinia stores bound to the active Nuxt instance via useNuxtApp(). - Engineers MUST NOT import server-only packages, filesystem drivers, or Nitro event utilities (e.g., getQuery, readBody, setResponseStatus) inside the app/ directory. - Engineers MUST ensure that any utilities shared between app/ and server/ placed in shared/ are strictly isomorphic, free of Node.js-only builtins (fs, path, crypto) and DOM-only APIs (window, document). - Server event handlers MUST return typed responses using defineEventHandler and avoid unhandled Promise rejections that crash the Nitro worker. - Engineers MUST use useRequestEvent() or useRequestHeaders() exclusively on the server branch and never mutate event.context directly across decoupled layers without schema validation. ## Bad vs Good Implementations ### Nitro Server Route & Shared State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scope variables in Nitro handlers survive individual requests. Under high concurrency in SSR or long-running worker runtimes, requests from User A will access or mutate state belonging to User B, triggering data cross-contamination and memory leaks. ```typescript // server/api/user.ts // ANTI-PATTERN: Mutable module-level state shared across all incoming HTTP requests let currentUserCache: Record<string, any> = {}; export default defineEventHandler(async (event) => { const id = getQuery(event).id as string; if (!currentUserCache[id]) { // Mutates global Node module state; leaks between different users' requests currentUserCache[id] = await fetchUserFromDb(id); } return currentUserCache[id]; }); ``` #### Production Standard (Correct) > **Standard**: State is scoped to the Nitro event lifecycle and official unstorage primitives. Request query inputs are explicitly validated with Zod, and data structures are typed via the isomorphic shared/ directory. ```typescript // server/api/user.ts // INVARIANT: Request-scoped cache using Nitro event context or isolated storage import { z } from 'zod'; import type { UserProfile } from '~~/shared/types/user'; const querySchema = z.object({ id: z.string().cuid() }); export default defineEventHandler(async (event): Promise<UserProfile> => { const { id } = await getValidatedQuery(event, querySchema.parse); // Cache using Nitro's isolated unstorage layer per tenant/key const storage = useStorage('cache:users'); const cached = await storage.getItem<UserProfile>(id); if (cached) { return cached; } const user = await fetchUserFromDb(id); await storage.setItem(id, user, { ttl: 60 }); return user; }); ``` ### Nuxt 4 SSR State Hydration in app/ Composables #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring a Vue ref() at the module root creates a singleton on the server instance. In SSR mode, that reference is shared across all concurrent users, causing severe cross-tenant hydration bugs and security violations. ```typescript // app/composables/useSession.ts // ANTI-PATTERN: Plain reactive reference declared in module scope import { ref } from 'vue'; // Leaks across requests on SSR server node runtime const globalUser = ref<any>(null); export const useSession = () => { const setUser = (user: any) => { globalUser.value = user; }; return { globalUser, setUser }; }; ``` #### Production Standard (Correct) > **Standard**: useState scopes the state instance to the current NuxtApp lifecycle via Nuxt SSR state serialization context. It guarantees thread-safe, request-isolated state on the server and synchronizes hydration on the client. ```typescript // app/composables/useSession.ts // INVARIANT: SSR-safe useState bound to active Nuxt request context import type { UserProfile } from '~~/shared/types/user'; export const useSession = () => { // useState is SSR-isolated per request key and serialized to client const user = useState<UserProfile | null>('auth:user', () => null); const setUser = (newUser: UserProfile | null) => { user.value = newUser; }; return { user: readonly(user), setUser }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Isolation, App Reorganization, and SSR Hydration Standard

Nuxt 4 Nitro Server Isolation, App Reorganization, and SSR Hydration Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between Nuxt 4 app/ runtime, Nitro server engine, and shared/ utilities. Prohibits global state pollution across concurrent SSR requests and eliminates cross-boundary imports between server and client domains. 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 Node Module State Leaks Across SSR Requests and Cross-Boundary Nitro Module Imports 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 Node Module State Leaks Across SSR Requests and Cross-Boundary Nitro Module Imports	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 Nuxt 4 frontend code within the app/ directory, backend Nitro logic within server/, and isomorphic primitives inside 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.