Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Hydration Guardrails

--- description: Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Hydration Guardrails - Enforces strict boundary separation between Nuxt 4 app/ frontend execution context, Nitro v2 server runtime, and the shared/ directory. Eliminates cross-request state pollution, server-side prototype leaks, and client bundle contamination by mandating per-request state instantiation and runtime-agnostic shared utilities. 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-isolation-standard" --- # Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Hydration Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Mutable State in Nitro Handlers and Direct Server Import into Nuxt 4 App Code ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 directory topology and Nitro runtime boundary isolation. You must ensure all Vue application code resides strictly under app/, server utilities under server/, and shared logic under shared/. Enforce zero-tolerance for global module-level mutable variables in Nitro routes and un-isolated SSR state sharing across concurrent client requests. ## Strict Guidelines - Engineers MUST ALWAYS locate client-facing components, composables, pages, and plugins strictly inside the `app/` directory pursuant to Nuxt 4 restructuring defaults. - Engineers MUST ALWAYS isolate SSR state using `useState()` or Pinia stores bound to `useNuxtApp()`; module-level `ref()`, `reactive()`, or plain JavaScript objects outside request scope are STRICTLY FORBIDDEN. - Engineers MUST NEVER import Nitro-only dependencies (e.g., `h3`, `#imports` containing server utilities, database connectors) into `app/` or `shared/`. - Engineers MUST ensure code located in `shared/` is strictly pure and runtime-agnostic; it MUST NOT reference Node.js built-ins (`fs`, `path`), browser globals (`window`, `localStorage`), or Nitro-specific context. - Nitro server event handlers MUST instantiate state per request or attach scoped context to `event.context`; they MUST NEVER write mutable data to module-scoped singleton variables. - Engineers MUST ALWAYS use `defineEventHandler` or `defineCachedEventHandler` with deterministic cache keys and avoid leaking sensitive backend headers or un-sanitized server state into client hydration payloads. ## Bad vs Good Implementations ### Module-Level Server State Leak vs Request-Scoped Context in Nitro Route #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `currentUser` at module scope in a Nitro server route creates a severe cross-request state pollution vulnerability where concurrent SSR requests overwrite and read each other's session data. ```typescript // server/api/user-session.ts import { defineEventHandler, getQuery } from 'h3'; // CRITICAL BUG: Shared mutable state across all concurrent SSR requests let currentUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const query = getQuery(event); if (query.userId) { currentUser = { id: String(query.userId), role: 'member' }; } return { user: currentUser }; }); ``` #### Production Standard (Correct) > **Standard**: Keeps request state strictly local to the handler execution scope and leverages `event.context` to avoid shared global references between concurrent incoming HTTP requests. ```typescript // server/api/user-session.ts import { defineEventHandler, getQuery, createError } from 'h3'; export default defineEventHandler(async (event) => { const query = getQuery(event); const userId = query.userId as string | undefined; if (!userId) { throw createError({ statusCode: 400, statusMessage: 'User ID required' }); } // Per-request isolation stored in Nitro event context or returned directly const user = { id: userId, role: 'member' }; event.context.user = user; return { user }; }); ``` ### SSR State Management: Module-Level Ref vs Nuxt useState Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a module-scoped `ref()` in an SSR environment causes state to persist within the server process, leaking data across different users and causing hydration mismatch errors on the client. ```typescript // app/composables/useUserProfile.ts import { ref } from 'vue'; // CRITICAL BUG: Module-level ref persists in Node process across all SSR requests const globalProfile = ref<{ name: string } | null>(null); export const useUserProfile = () => { const setProfile = (name: string) => { globalProfile.value = { name }; }; return { globalProfile, setProfile }; }; ``` #### Production Standard (Correct) > **Standard**: Uses `useState()` with a unique key, ensuring that state is scoped to the current NuxtApp SSR lifecycle, correctly serialized into the payload, and safely hydrated in the client DOM. ```typescript // app/composables/useUserProfile.ts export interface UserProfile { name: string; } export const useUserProfile = () => { // Invariant: useState provides request-isolated SSR state serialized to payload const profile = useState<UserProfile | null>('user_profile_state', () => null); const setProfile = (name: string) => { profile.value = { name }; }; return { profile: readonly(profile), setProfile }; }; ``` ### Runtime-Agnostic Types & Validation in Nuxt 4 Shared Directory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Node.js built-in modules into `shared/` causes client build failures or polyfill bloat when imported inside `app/` Vue components. ```typescript // shared/utils/formatter.ts // ANTI-PATTERN: Polluting shared/ with Node.js built-ins breaking client bundle import { resolve } from 'node:path'; export const formatFilePath = (fileName: string) => { return resolve(process.cwd(), 'uploads', fileName); }; ``` #### Production Standard (Correct) > **Standard**: Shared folder contains pure validation logic and TypeScript contracts compatible with both server-side Nitro validation and client-side form validation. ```typescript // shared/utils/validators.ts import { z } from 'zod'; // Invariant: Pure, runtime-agnostic schema importable by both Nitro and Vue export const UserPayloadSchema = z.object({ id: z.string().uuid(), displayName: z.string().min(2).max(50), email: z.string().email() }); export type UserPayload = z.infer<typeof UserPayloadSchema>; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Hydration Guardrails

Nuxt 4 Directory Restructuring, Nitro Isolation, and SSR State Hydration Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between Nuxt 4 app/ frontend execution context, Nitro v2 server runtime, and the shared/ directory. Eliminates cross-request state pollution, server-side prototype leaks, and client bundle contamination by mandating per-request state instantiation and runtime-agnostic shared utilities. 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 Mutable State in Nitro Handlers and Direct Server Import into Nuxt 4 App Code 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 Mutable State in Nitro Handlers and Direct Server Import into Nuxt 4 App Code	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 locate client-facing components, composables, pages, and plugins strictly inside the `app/` directory pursuant to Nuxt 4 restructuring defaults.

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.