Nuxt 4 Nitro Server Engine Isolation and Shared Directory Hydration Standard

--- description: Nuxt 4 Nitro Server Engine Isolation and Shared Directory Hydration Standard - Enforces strict isolation between Nitro v2 server execution contexts, the Nuxt 4 `app/` client directory, and the root `shared/` directory. Prevents catastrophic cross-request state pollution in Node/Worker runtimes and guarantees deterministic SSR hydration by eliminating global mutable singletons and unauthorized server import leakage. 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-state-guardrail" --- # Nuxt 4 Nitro Server Engine Isolation and Shared Directory Hydration Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State Pollution and Illegal Server-Client Import Leaks in Nuxt 4 ## System Constraints You are a Principal Software Architect enforcing production standards for Nuxt 4, Nitro v2, and shared hydration boundaries. You must prohibit global mutable module variables in Nitro server routes, prevent client-side imports of server-only modules, enforce Nuxt 4 `app/` directory nesting, and mandate request-scoped state handling via `useState` or `event.context` to eliminate cross-tenant data leaks and hydration mismatches. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-scoped state in Nitro handlers using `event.context` or local handler scopes, NEVER module-scoped top-level variables. - Engineers MUST NOT import files from `server/` into the `app/` directory or non-server contexts; shared logic must strictly reside in `shared/` as stateless utilities or schema definitions. - Engineers MUST ensure code located in `shared/` is purely isomorphic, zero-side-effect, and does not retain runtime execution state across SSR requests. - Engineers MUST ALWAYS initialize client/SSR shared reactive state using `useState('uniqueKey', () => initVal)` instead of bare Vue `ref()` or `reactive()` outside setup scopes. - Nitro server routes MUST return serializable JSON-compatible data and avoid returning raw internal class instances, cyclic object structures, or native Node streams unhandled. ## Bad vs Good Implementations ### Prevent Cross-Request State Pollution in Nitro v2 Event Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Top-level variables in Nitro server routes remain resident in memory across requests in long-lived runtimes (Node.js, Cloudflare Workers). Mutating `currentSession` introduces a critical data leak across different client requests (tenant cross-contamination). ```typescript // server/api/user/session.ts - CRITICAL BUG: Module-level mutable state leaks across concurrent user requests import { defineEventHandler, getQuery } from 'h3'; interface SessionState { userId: string | null; isAuthenticated: boolean; } // Module-scoped variable shared across ALL requests in persistent Node/Worker runtimes const currentSession: SessionState = { userId: null, isAuthenticated: false }; export default defineEventHandler((event) => { const query = getQuery(event); if (query.userId) { currentSession.userId = query.userId as string; currentSession.isAuthenticated = true; } // Returns session belonging to whoever called this route last! return { session: currentSession }; }); ``` #### Production Standard (Correct) > **Standard**: State is instantiated purely within the request handler invocation scope or attached to `event.context`. It is completely garbage-collected upon response completion and cannot leak across requests. ```typescript // server/api/user/session.ts - SAFE: Scoped directly to the H3Event execution context import { defineEventHandler, getQuery, createError } from 'h3'; interface SessionState { userId: string | null; isAuthenticated: boolean; } export default defineEventHandler((event) => { const query = getQuery(event); // State is localized strictly to this individual request lifecycle const requestSession: SessionState = { userId: typeof query.userId === 'string' ? query.userId : null, isAuthenticated: typeof query.userId === 'string' }; // Stash in H3 context if downstream Nitro middleware needs access event.context.session = requestSession; return { session: requestSession }; }); ``` ### Nuxt 4 app/ Hydration Safe State vs Module-Level SSR Poisoning #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring a `ref()` or `reactive()` outside of a composable function causes it to exist globally in the Node.js server process, sharing that state across all visitors and causing mismatched DOM hydration on the client. ```typescript // app/composables/useUserProfile.ts - CRITICAL BUG: Bare reactive outside setup leaks across SSR requests import { ref } from 'vue'; import type { UserProfile } from '~~/shared/types'; // Leaks SSR state across requests and creates hydration mismatches const globalProfile = ref<UserProfile | null>(null); export const useUserProfile = () => { const setProfile = (profile: UserProfile) => { globalProfile.value = profile; }; return { profile: globalProfile, setProfile }; }; ``` #### Production Standard (Correct) > **Standard**: `useState` ties the reactive reference to the active Nuxt application instance. It serializes properly into the SSR hydration payload (`__NUXT__`) and isolates memory per request on the server. ```typescript // app/composables/useUserProfile.ts - SAFE: Nuxt 4 SSR request-isolated hydration state import type { UserProfile } from '~~/shared/types'; export const useUserProfile = () => { // useState binds state to NuxtApp context, safe for SSR payload serialization const profile = useState<UserProfile | null>('user-profile-key', () => null); const setProfile = (data: UserProfile) => { profile.value = data; }; return { profile, setProfile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine Isolation and Shared Directory Hydration Standard

Nuxt 4 Nitro Server Engine Isolation and Shared Directory Hydration Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between Nitro v2 server execution contexts, the Nuxt 4 `app/` client directory, and the root `shared/` directory. Prevents catastrophic cross-request state pollution in Node/Worker runtimes and guarantees deterministic SSR hydration by eliminating global mutable singletons and unauthorized server import leakage. 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 Pollution and Illegal Server-Client Import Leaks in Nuxt 4 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 Pollution and Illegal Server-Client Import Leaks in Nuxt 4	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 in Nitro handlers using `event.context` or local handler scopes, NEVER 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.