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

--- description: Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation - Enforces strict boundary separation between Nuxt 4's app/ directory, Nitro server runtime, and shared/ utilities. Prevents cross-request state pollution, runtime leakage of server-only primitives into client bundles, and un-isolated SSR state hydration bugs. globs: app/**/*.{ts,vue}, server/**/*.{ts,js}, shared/**/*.{ts,js}, nuxt.config.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt4-nitro-shared-ssr-guardrails" --- # Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State in Nitro Handlers and Cross-Polluting Shared Directory Imports ## System Constraints You are a Principal Software Architect enforcing production invariants for Nuxt 4, Nitro v2/v3 server runtimes, and SSR hydration. Mandate absolute memory isolation across incoming SSR requests, ensure proper usage of the shared/ directory without leaking server context or client Vue reactivity, and prevent hydration mismatch or security leaks caused by shared singletons. ## Strict Guidelines - Engineers MUST NEVER declare global or module-scoped state variables within Nitro server handlers or composables that mutate per request. - Engineers MUST ALWAYS isolate SSR state per request using `useState()` in the Nuxt app context and event context (`event.context`) in Nitro handlers. - Engineers MUST ensure code placed in the `shared/` directory contains only isomorphic, pure logic, validation schemas (e.g., Zod), and shared types, with ZERO dependencies on Vue reactivity (`ref`, `reactive`) or Node/Nitro server primitives (`H3Event`, `fs`, `useStorage`). - Engineers MUST NOT import server-only packages, Nitro utilities, or private server runtime configurations into `app/` or isomorphic `shared/` files. - Engineers MUST explicitly utilize `defineEventHandler` in Nitro routes and avoid raw Node HTTP request mutations. - Components NEVER store sensitive server payloads or non-serializable objects in `useState()` or `useAsyncData()` payloads destined for SSR hydration transfer. ## Bad vs Good Implementations ### Cross-Request Memory Leak in Nitro Handler vs. Event-Isolated Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scoped variables in Nitro server routes persist across concurrent and subsequent HTTP requests on warm server instances, leaking sensitive session state across distinct users. ```typescript // server/api/user-session.ts import { defineEventHandler } from 'h3'; // CRITICAL BUG: Module-scoped state shared across all concurrent requests in the Nitro Node/V8 runtime! let currentUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { currentUser = await verifyToken(token); } // Subsequent requests will leak the previous user's credentials return { user: currentUser }; }); ``` #### Production Standard (Correct) > **Standard**: State is securely constrained to the current execution frame and H3Event context, strictly preventing cross-request pollution. ```typescript // server/api/user-session.ts import { defineEventHandler, getHeader, createError } from 'h3'; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, message: 'Unauthorized' }); } // SAFE: Scoped directly to the individual H3Event context const user = await verifyToken(token); event.context.user = user; return { user }; }); ``` ### Contaminated Shared Directory Logic vs. Isomorphic Pure Utility #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactivity or Nitro-specific `#imports` into the `shared/` directory breaks isomorphism, breaks bundling on the opposite side, and introduces reactivity hazards outside Vue scope. ```typescript // shared/utils/auth.ts import { ref } from 'vue'; // VIOLATION: Injecting Vue reactivity into shared engine logic import { useStorage } from '#imports'; // VIOLATION: Nitro server-only virtual import export const authState = ref(null); export async function getCachedToken(key: string) { const storage = useStorage('redis'); return await storage.getItem(key); } ``` #### Production Standard (Correct) > **Standard**: The shared utility remains pure, containing only serializable types and isomorphic validations usable seamlessly by both `app/` Vue components and `server/` Nitro routes. ```typescript // shared/utils/auth.ts import { z } from 'zod'; // SAFE: Isomorphic schema validation compatible with app/, server/, and edge runtimes export const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email(), role: z.enum(['admin', 'member', 'guest']) }); export type User = z.infer<typeof UserSchema>; export function isValidUser(data: unknown): data is User { return UserSchema.safeParse(data).success; } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine, Shared Directory, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between Nuxt 4's app/ directory, Nitro server runtime, and shared/ utilities. Prevents cross-request state pollution, runtime leakage of server-only primitives into client bundles, and un-isolated SSR state hydration bugs. 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 in Nitro Handlers and Cross-Polluting Shared Directory 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 Module-Level State in Nitro Handlers and Cross-Polluting Shared Directory 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 NEVER declare global or module-scoped state variables within Nitro server handlers or composables that mutate per request.

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.