Nuxt 4 Nitro Server Engine & Shared Directory SSR State Isolation Standard

--- description: Nuxt 4 Nitro Server Engine & Shared Directory SSR State Isolation Standard - Nuxt 4 transitions the client application root to the app/ directory while leveraging shared/ for universal types and constants, requiring complete boundary isolation from the server/ Nitro runtime. Un-isolated global module-level state in Nitro event handlers or shared modules leaks across concurrent SSR request contexts, resulting in cross-tenant data corruption and security compromise. globs: app/**/*.{vue,ts,js}, 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-directory-ssr-isolation-guardrail" --- # Nuxt 4 Nitro Server Engine & Shared Directory SSR State Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Scope Mutable State Leakage in Nitro Handlers and Improper Nuxt 4 Directory Cross-Imports ## System Constraints You are a Principal Software Architect enforcing architectural boundaries and SSR state safety for Nuxt 4. You must enforce strict isolation between the app/ directory, server/ Nitro engine, and shared/ universal modules. Any mutable state declared at module scope in Nitro event handlers or shared code constitutes a catastrophic cross-request data breach and must be blocked. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-specific state in Nitro event handlers using event.context or by instantiating services inside defineEventHandler. - Engineers MUST NOT declare mutable module-level variables (e.g., let currentUser, const cache = new Map()) in Nitro server routes, middleware, or plugins. - Engineers MUST place universal TypeScript interfaces, schemas, and purely functional utilities inside the shared/ directory, never client-specific or server-specific runtime modules. - Engineers MUST NOT import server/ files into app/ or import app/ runtime code (such as Vue composables or useNuxtApp) into server/ routes. - Engineers MUST ALWAYS use useState() or Nuxt's SSR-safe primitives within app/ rather than global reactive variables (ref/reactive outside setup/composable) to avoid SSR cross-tenant hydration leakage. - Nitro route handlers MUST validate untrusted payloads at the edge using runtime schema validators (e.g., Zod, Valibot) before passing parsed data into domain services. ## Bad vs Good Implementations ### Module-Level Mutable State in Nitro Event Handler (Cross-Tenant Leak) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring currentUserSession at the module scope retains data in the persistent Node.js/Nitro process across requests. Under concurrent traffic, Request B overwrites currentUserSession while Request A is awaiting I/O, resulting in Request A receiving Request B's credentials. ```typescript // server/api/user/profile.get.ts import { defineEventHandler, getQuery } from 'h3'; // CRITICAL ANTI-PATTERN: Module-scope mutable state is shared across ALL concurrent requests let currentUserSession: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const query = getQuery(event); currentUserSession = { id: String(query.userId), role: 'authenticated' }; // Async boundary allows interleaved concurrent requests to overwrite currentUserSession await new Promise((resolve) => setTimeout(resolve, 50)); return { session: currentUserSession }; }); ``` #### Production Standard (Correct) > **Standard**: Variables are strictly scoped to the execution context of the event handler. Nitro request context (event.context) is uniquely instantiated per incoming HTTP request, ensuring complete isolation across concurrent tenants. ```typescript // server/api/user/profile.get.ts import { defineEventHandler, getValidatedQuery } from 'h3'; import { z } from 'zod'; import type { UserSession } from '~~/shared/types/auth'; const querySchema = z.object({ userId: z.string().uuid() }); export default defineEventHandler(async (event): Promise<{ session: UserSession }> => { // Request-isolated scoped evaluation via getValidatedQuery const { userId } = await getValidatedQuery(event, (data) => querySchema.parse(data)); // State lives strictly within the handler scope and Nitro event.context const session: UserSession = { id: userId, role: 'authenticated', retrievedAt: new Date().toISOString() }; event.context.userSession = session; return { session }; }); ``` ### Nuxt 4 app/ and shared/ Directory Hydration Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactivity primitives into shared/ to create module-level reactive objects leaks state across requests on the SSR server node, polluting all visitor sessions with shared singleton memory. ```typescript // shared/utils/user.ts import { ref } from 'vue'; // ANTI-PATTERN: Client reactivity leak in universal shared/ directory export const globalUser = ref<{ name: string } | null>(null); // app/composables/useUser.ts import { globalUser } from '~~/shared/utils/user'; export const useUser = () => { return { user: globalUser }; }; ``` #### Production Standard (Correct) > **Standard**: Types are cleanly separated into shared/ without runtime framework side-effects. The composable in app/ uses useState(), which serializes state on the server and safely rehydrates it in the client without SSR node leakage. ```typescript // shared/types/user.ts export interface UserProfile { id: string; name: string; email: string; } // app/composables/useUser.ts import { useState } from '#imports'; import type { UserProfile } from '~~/shared/types/user'; export const useUser = () => { // SSR-safe state hydration keyed specifically per request lifecycle const user = useState<UserProfile | null>('auth-user-profile', () => null); const setUser = (profile: UserProfile | null) => { user.value = profile; }; return { user, setUser }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine & Shared Directory SSR State Isolation Standard

Nuxt 4 Nitro Server Engine & Shared Directory SSR State Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 transitions the client application root to the app/ directory while leveraging shared/ for universal types and constants, requiring complete boundary isolation from the server/ Nitro runtime. Un-isolated global module-level state in Nitro event handlers or shared modules leaks across concurrent SSR request contexts, resulting in cross-tenant data corruption and security compromise. 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-Scope Mutable State Leakage in Nitro Handlers and Improper Nuxt 4 Directory Cross-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-Scope Mutable State Leakage in Nitro Handlers and Improper Nuxt 4 Directory Cross-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 isolate request-specific state in Nitro event handlers using event.context or by instantiating services inside defineEventHandler.

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.