/web-meta-framework-nuxt

name: web-meta-framework-nuxt
description: Nuxt patterns - file-based routing, data fetching (useFetch/useAsyncData), useState, server routes, middleware, auto-imports, layouts, SEO

Nuxt Framework Patterns

> **Quick Guide:** `useFetch` for an API call in a component, `useAsyncData` for a custom source or > several fetches combined — both transfer the server's result to the client so nothing is fetched > twice. Server routes live in `server/api/`, shared state in `useState`, and composables and > components are auto-imported. Two facts change the answers below: `data` is a `shallowRef`, so > replace the object rather than mutating into it (or pass `deep: true`), and `data` and `error` > default to `undefined` rather than `null`.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — pages, layouts, error handling, SEO composables, plugins, runtime config
• [examples/data-fetching.md](examples/data-fetching.md) — typed responses, transforms, lazy and server-only fetching
• [examples/server-routes.md](examples/server-routes.md) — CRUD handlers, validation, server middleware, error utilities
• [examples/middleware.md](examples/middleware.md) — auth guards, role checks, global and inline middleware
• [examples/state-management.md](examples/state-management.md) — `useState` composables, cookie persistence, server-initialised state
• [reference.md](reference.md) — decision trees, directory conventions, per-area checklists

---

Which path applies

• **Rendering a page** — routing, layouts and SEO are file conventions plus two composables; follow

[examples/core.md](examples/core.md).

• **Getting data into a page** — the choice is `useFetch` versus `useAsyncData`, and everything else

is options on them; follow [examples/data-fetching.md](examples/data-fetching.md).

• **Writing the API the page calls** — `server/api/` handlers run under Nitro with their own

utilities; follow [examples/server-routes.md](examples/server-routes.md).

• **Guarding navigation** — route middleware runs on both server and client; follow

[examples/middleware.md](examples/middleware.md).

---

<critical_requirements>

Before writing Nuxt code

**Fetch through `useFetch` or `useAsyncData` rather than a bare `$fetch` in `<script setup>`.** Both carry the server's payload into hydration; a bare `$fetch` there runs twice, once per environment.

**Put API routes in `server/api/` and export a `defineEventHandler()` as the default.** The file suffix (`.get.ts`, `.post.ts`) is what restricts the method, and the directory is what adds the `/api` prefix.

**Attach middleware and page options through `definePageMeta`.** It is a compile-time macro, so its argument has to be statically analysable — no variables, no computed keys.

**Set metadata with `useHead` or `useSeoMeta`.** Both render server-side and merge with the defaults in `nuxt.config.ts`, which hand-written `<head>` markup does not.

**Keep `useState` values JSON-serializable.** The value is serialised into the HTML and revived on the client, so a function, class instance or Symbol breaks hydration.

**Read `to` and `from` inside route middleware rather than calling `useRoute()`.** The route object has not been committed yet at that point, so `useRoute()` answers with the previous route.

</critical_requirements>

---

**Auto-detection:** nuxt.config.ts, defineNuxtConfig, useFetch, useAsyncData, useState, useCookie, useRuntimeConfig, useNuxtApp, defineEventHandler, definePageMeta, defineNuxtRouteMiddleware, defineNuxtPlugin, navigateTo, abortNavigation, createError, clearError, showError, useHead, useSeoMeta, NuxtLayout, NuxtPage, NuxtLink, NuxtErrorBoundary, server/api, $fetch, h3, import.meta.client, import.meta.server

**Applies to:**

• File-based routing over `pages/`, with layouts, dynamic segments and catch-all routes
• SSR-safe data fetching, and the transform, lazy and pick options that shape the payload
• Server routes and server middleware in the same project as the pages
• Shared reactive state that survives the server-to-client boundary
• Navigation guards for authentication, authorization and feature flags
• SEO metadata, plugins, and public versus private runtime configuration

**Handled elsewhere:**

• Vue component authoring itself — reactivity, template syntax and component composition
• Persistence — a server route calls a data layer; neither the client nor the query shape is settled

here

• Schema validation — a handler parses `readBody` through a schema; which library defines it is a

separate choice

• Styling — components take classes, and the styling approach is someone else's
• Application state that needs devtools, time-travel or cross-store dependencies, which `useState`

deliberately does not provide

---

<philosophy>

Philosophy

Nuxt is a meta-framework for Vue 3: file-based routing, automatic code splitting, server-side rendering, and a data-fetching layer that knows about hydration. It runs on the Nitro server engine, so API routes live in the same project as the pages that call them.

Five ideas explain most of the API surface:

1. **Universal rendering by default** — a page renders on the server first, then hydrates 2. **Auto-imports** — composables, components and utilities are available without an import line, so an unfamiliar `useX` is usually Nuxt's own 3. **File-based conventions** — `pages/`, `server/`, `layouts/`, `middleware/` each mean something 4. **Hydration-aware fetching** — the composables exist because the naive fetch runs twice 5. **Shallow reactivity** — `data` is a `shallowRef`; deep tracking is a cost Nuxt does not pay by default

</philosophy>

---

<patterns>

Core patterns

Pattern 1: File-Based Routing

File names in `pages/` become URL paths, and bracket depth chooses the kind of segment.

| File | URL | | ---------------------------- | ------------------------ | | `pages/index.vue` | `/`