Nuxt 4 Directory Topology, Nitro State Isolation, and Shared Module Purity

--- description: Nuxt 4 Directory Topology, Nitro State Isolation, and Shared Module Purity - Enforces strict architectural boundaries across the Nuxt 4 app/, server/, and shared/ directory structure, preventing cross-request state pollution in Nitro v2 execution contexts. Guarantees pure platform-agnostic shared utilities and hydration-safe SSR state allocation. 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-hydration-guardrails" --- # Nuxt 4 Directory Topology, Nitro State Isolation, and Shared Module Purity > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Leakage in Nitro Handlers and Platform Contamination in Shared Directory ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 directory topology, Nitro v2 execution invariants, and SSR state hydration safety. You must prevent cross-request state leakage in persistent server runtime processes, ensure root 'shared/' modules remain strictly platform-agnostic, and verify that the 'app/' directory restructuring is completely respected without legacy Nuxt 3 directory bleed. ## Strict Guidelines - Engineers MUST ALWAYS place client-side Nuxt 4 application layers within the 'app/' directory (e.g., app/components/, app/composables/, app/pages/, app/middleware/) unless explicitly configured otherwise. - Engineers MUST NEVER declare mutable state at the module scope in Nitro event handlers, Nitro plugins, or SSR composables, as persistent worker runtimes (Node.js/Bun/Workers) will share this state across concurrent user requests. - Engineers MUST ALWAYS use `useState<T>()` with unique, deterministic keys for client-server state hydration, and NEVER use module-level `ref()` or `reactive()` outside setup scopes. - Code inside the root `shared/` directory MUST remain purely isomorphic and platform-agnostic; it MUST NOT import browser-specific globals (window, document, localStorage) or server-specific packages (h3, node:*, nitro runtime utilities). - Nitro route handlers MUST encapsulate request state strictly via `event.context` or parameter pass-through, relying exclusively on `defineEventHandler` with typed input validation. - Services interacting with server responses during SSR MUST ensure payload serialization compatibility; instances of non-serializable objects (e.g., native Map, Set, class instances with private methods) MUST NOT be returned directly without custom Nitro transformers or explicit JSON mappers. ## Bad vs Good Implementations ### Nitro Server Route & Hydration State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In long-running Nitro server environments (Node.js cluster, Cloudflare Workers, Nitro standalone), module-level variables persist across independent HTTP requests. Caching request-derived user information in top-level variables leaks private data between concurrent client requests. ```typescript // server/api/user.ts - SEVERE SECURITY RISK: Module-scoped state leaks across tenant requests let currentUserCache: Record<string, any> = {}; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token && !currentUserCache[token]) { // Mutating persistent shared memory across requests currentUserCache[token] = await fetchUserData(token); } return currentUserCache[token] ?? null; }); ``` #### Production Standard (Correct) > **Standard**: Shared types are placed in root `shared/`, the Nitro handler avoids module-scoped mutations by encapsulating state strictly inside `event.context`, and the Vue application consumes it safely using `useState()` within the Nuxt 4 `app/` directory. ```typescript // shared/types/user.ts - Pure isomorphic domain contract export interface UserProfile { id: string; tenantId: string; email: string; } // server/api/user.get.ts - Request-scoped execution using event.context export default defineEventHandler(async (event): Promise<UserProfile | null> => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Cache strictly within Nitro's per-request context if (!event.context.user) { event.context.user = await fetchUserData(token); } return event.context.user as UserProfile; }); // app/composables/useUserProfile.ts - Safe SSR state hydration export const useUserProfile = () => { // Deterministic hydration key prevents mismatch and cross-request leakage const user = useState<UserProfile | null>('user-session-profile', () => null); const fetchProfile = async () => { const { data } = await useFetch<UserProfile>('/api/user'); user.value = data.value; }; return { user: readonly(user), fetchProfile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Topology, Nitro State Isolation, and Shared Module Purity

Nuxt 4 Directory Topology, Nitro State Isolation, and Shared Module Purity defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural boundaries across the Nuxt 4 app/, server/, and shared/ directory structure, preventing cross-request state pollution in Nitro v2 execution contexts. Guarantees pure platform-agnostic shared utilities and hydration-safe SSR state allocation. 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: Cross-Request State Leakage in Nitro Handlers and Platform Contamination in Shared Directory 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	Cross-Request State Leakage in Nitro Handlers and Platform Contamination in Shared Directory	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 place client-side Nuxt 4 application layers within the 'app/' directory (e.g., app/components/, app/composables/, app/pages/, app/middleware/) unless explicitly configured otherwise.

Engineers MUST ALWAYS place client-side Nuxt 4 application layers within the 'app/' directory (e.g., app/components/, app/composables/, app/pages/, app/middleware/) unless explicitly configured otherwise.

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.