Nuxt 4 Directory Boundaries, Nitro Request Context, and SSR State Isolation

--- description: Nuxt 4 Directory Boundaries, Nitro Request Context, and SSR State Isolation - Enforces strict boundary isolation between Nuxt 4's app/ directory, Nitro server runtime, and shared/ utilities. Eliminates cross-request state pollution, module-scope SSR memory leaks, and invalid runtime cross-imports between Nitro event handlers and client components. globs: app/**/*.{vue,ts,js}, 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-boundary-guardrail" --- # Nuxt 4 Directory Boundaries, Nitro Request Context, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Singletons in Nitro Handlers and Leaking Server Runtime Logic into app/ Components ## System Constraints You are a Principal Software Architect enforcing strict runtime boundary isolation and hydration safety in Nuxt 4 and Nitro v2. Mandate the correct usage of the Nuxt 4 app/ root restructuring, the shared/ layer, request-scoped context in Nitro, and per-request SSR state management using useState instead of module-level reactive state. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR client state using Nuxt's useState() keyed composable and NEVER declare mutable reactive state (ref, reactive) at top-level module scope in app/ or server/. - Engineers MUST place all frontend application logic inside the app/ directory according to Nuxt 4 conventions, maintaining app/components, app/composables, and app/pages. - Code placed in shared/ MUST be strictly pure TypeScript containing only cross-environment types, pure mathematical/formatting utilities, and zero-dependency schemas, with no references to h3, Nitro, or Vue runtime APIs. - Nitro server routes in server/api/ and server/routes/ MUST ALWAYS access request state exclusively via H3Event (e.g., event.context, getRouterParam, readBody) and NEVER cache per-request data in module-level global variables. - Components and composables in app/ MUST NEVER import directly from server/ (except for type-only imports matching Nitro route return signatures). - Nitro server handlers MUST NEVER import Vue reactivity APIs (ref, reactive, computed) or Nuxt app composables (useRoute, useRouter, useState, useNuxtApp). ## Bad vs Good Implementations ### SSR State Isolation & Module-Level Singleton Elimination #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'ref' or 'reactive' at top-level module scope causes cross-request state pollution. Node/Nitro server processes persist this memory across requests, causing User B to see User A's cached state during SSR. ```typescript // app/composables/useUserProfile.ts import { ref } from 'vue'; // ANTI-PATTERN: Top-level module variable leaks state across concurrent SSR requests const globalUser = ref<{ id: string; name: string } | null>(null); export const useUserProfile = () => { const setUser = (user: { id: string; name: string }) => { globalUser.value = user; }; return { user: globalUser, setUser }; }; ``` #### Production Standard (Correct) > **Standard**: useState creates a per-request isolated state on the server, serializes it into window.__NUXT__, and seamlessly hydrates it on the client without leaking across concurrent requests. ```typescript // app/composables/useUserProfile.ts import type { Ref } from 'vue'; import type { UserProfile } from '~~/shared/types/user'; export const useUserProfile = () => { // Invariant: useState wraps SSR-safe per-request hydration keys const user: Ref<UserProfile | null> = useState<UserProfile | null>( 'user-profile-session', () => null ); const setUser = (newUser: UserProfile) => { user.value = newUser; }; return { user, setUser }; }; ``` ### Nitro Request Context and Shared Directory Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Imports Vue/client composables into the Nitro runtime and relies on a mutable in-memory cache shared across all incoming HTTP requests without boundary checks. ```typescript // server/api/user.get.ts import { userSessionCache } from '../utils/cache'; // Module-level mutable Map import { useRoute } from 'vue-router'; // INVALID: Importing client/Nuxt app composable export default defineEventHandler((event) => { const route = useRoute(); const cached = userSessionCache.get(event.node.req.headers['x-session-id']); return cached || { user: 'anonymous' }; }); ``` #### Production Standard (Correct) > **Standard**: Leverages pure h3 event primitives, imports types safely from shared/, avoids client imports, and keeps request evaluation scoped strictly to the current H3Event context. ```typescript // server/api/user.get.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserProfile } from '~~/shared/types/user'; import { validateSessionToken } from '../utils/auth'; export default defineEventHandler(async (event): Promise<UserProfile> => { const sessionId = getHeader(event, 'x-session-id'); if (!sessionId) { throw createError({ statusCode: 401, statusMessage: 'Session header missing' }); } // Request-isolated lookup using event.context const user = await validateSessionToken(event, sessionId); return user; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Boundaries, Nitro Request Context, and SSR State Isolation

Nuxt 4 Directory Boundaries, Nitro Request Context, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between Nuxt 4's app/ directory, Nitro server runtime, and shared/ utilities. Eliminates cross-request state pollution, module-scope SSR memory leaks, and invalid runtime cross-imports between Nitro event handlers and client components. 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 Singletons in Nitro Handlers and Leaking Server Runtime Logic into app/ Components 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 Singletons in Nitro Handlers and Leaking Server Runtime Logic into app/ Components	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 SSR client state using Nuxt's useState() keyed composable and NEVER declare mutable reactive state (ref, reactive) at top-level module scope in app/ or server/.

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.