--- 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:** Use `useFetch` for API calls in components (SSR-safe), `useAsyncData` for custom data sources or parallel fetches. Create server routes in `server/api/`. Auto-imports handle composables and components automatically. Use `useState` for SSR-friendly shared state. Data is a `shallowRef` by default -- use `deep: true` if you need deep reactivity. --- ## CRITICAL: Before Using This Skill > **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants) **(You MUST use `useFetch` or `useAsyncData` for data fetching in components -- NEVER raw `$fetch` in setup which causes double-fetching)** **(You MUST use `server/api/` for API routes -- handlers export default with `defineEventHandler()`)** **(You MUST use `definePageMeta` to attach middleware and configure page behavior -- it is a macro, values must be statically analyzable)** **(You MUST use `useHead` or `useSeoMeta` for SEO metadata -- never manual `` tags)** **(You MUST ensure `useState` values are JSON-serializable for SSR hydration -- no functions, classes, or Symbols)** --- **Auto-detection:** Nuxt, nuxt.config.ts, useFetch, useAsyncData, useState, defineEventHandler, definePageMeta, defineNuxtRouteMiddleware, NuxtLayout, NuxtPage, NuxtLink, navigateTo, server/api, pages/, layouts/, middleware/, composables/, useHead, useSeoMeta, app/ directory **When to use:** - Building Vue 3 applications with file-based routing and SSR/SSG - Creating full-stack applications with server routes in the same project - Implementing data fetching that works seamlessly across server and client - Building SEO-optimized pages with automatic metadata handling - Leveraging auto-imports for composables and components **Key patterns covered:** - File-based routing (pages/, dynamic routes, catch-all routes) - Data fetching (useFetch, useAsyncData, $fetch) - Server routes (server/api/, defineEventHandler) - Shared state (useState composable) - Route middleware (defineNuxtRouteMiddleware, navigateTo) - Layouts (layouts/, NuxtLayout, setPageLayout) - SEO (useHead, useSeoMeta) - Plugins (plugins/, defineNuxtPlugin) - Error handling (NuxtErrorBoundary, createError, showError) - Auto-imports (composables, components, utils) **When NOT to use:** - Simple SPAs without SSR needs (consider Vue + Vite directly) - Static documentation sites without server logic (consider a static-site generator) --- ## Philosophy Nuxt is a **meta-framework for Vue 3** that provides file-based routing, automatic code splitting, server-side rendering, and a powerful data-fetching system. Built on Nitro server engine, it enables full-stack development with API routes colocated with your frontend. **Core Principles:** 1. **Universal rendering by default** -- Pages render on server first, then hydrate on client 2. **Auto-imports everywhere** -- Composables, components, and utilities are automatically available 3. **File-based conventions** -- Directories define behavior (pages/, server/, layouts/, middleware/) 4. **SSR-safe data fetching** -- Composables prevent double-fetching between server and client 5. **Zero-config TypeScript** -- Full type safety with automatic type generation 6. **Shallow reactivity for performance** -- `data` from `useFetch`/`useAsyncData` is a `shallowRef` by default --- ## Core Patterns ### Pattern 1: File-Based Routing File names in `pages/` become URL paths. Dynamic segments use bracket syntax. | File | URL | Description | | --------------------------- | ------------------------ | ------------------ | | `pages/index.vue` | `/` | Home page | | `pages/about.vue` | `/about` | Static route | | `pages/blog/[slug].vue` | `/blog/:slug` | Dynamic parameter | | `pages/users/[...slug].vue` | `/users/*` | Catch-all route | | `pages/posts/[[id]].vue` | `/posts` or `/posts/:id` | Optional parameter | ```vue ``` **Why good:** File names map to URLs, bracket syntax for dynamic params, createError triggers error page See [examples/core.md](examples/core.md) for complete page examples with layouts and middleware. --- ### Pattern 2: Data Fetching (useFetch / useAsyncData) `useFetch` wraps `useAsyncData` + `$fetch`. It prevents double-fetching by transferring server data to client during hydration. Data is a `shallowRef` -- replace the whole object to trigger reactivity, or use `deep: true`. ```typescript // Simple fetch -- URL is cache key const { data, error, status, refresh, clear } = await useFetch("/api/users"); // With reactive query params and auto-refetch const page = ref(1); const { data: users } = await useFetch("/api/users", { query: { page, limit: 20 }, watch: [page], }); // POST with immediate: false for user-triggered actions const { execute, status } = useFetch("/api/users", { method: "POST", body: form, immediate: false, watch: false, }); ``` Use `useAsyncData` when combining multiple fetches or using non-HTTP sources: ```typescript const { data } = await useAsyncData("dashboard", async () => { const [users, stats] = await Promise.all([ $fetch("/api/users"), $fetch("/api/stats"), ]); return { users, stats }; }); ``` **Critical:** `$fetch` in ` ``` **Why good:** Reactive values with getter functions, type-safe property names, automatic Open Graph and Twitter cards, SSR-rendered Global defaults in `nuxt.config.ts` via `app.head`. Page-level overrides via composables. --- ### Pattern 8: Plugins Plugins run before Vue app creation. Use for registering global utilities or external libraries. ```typescript // plugins/api.client.ts -- .client suffix = browser only export default defineNuxtPlugin(() => { const config = useRuntimeConfig(); const api = $fetch.create({ baseURL: config.public.apiBase, onRequest({ options }) { const token = useCookie("token"); if (token.value) { options.headers = { ...options.headers, Authorization: `Bearer ${token.value}`, }; } }, }); return { provide: { api } }; }); ``` Access via `useNuxtApp().$api`. Suffixes: `.client.ts` (browser), `.server.ts` (server), no suffix (both). --- ### Pattern 9: Error Handling ```typescript // Server route errors throw createError({ statusCode: 404, statusMessage: "Not found", data: { id }, }); // Page-level: check useFetch error, throw createError // Component-level: NuxtErrorBoundary with #error slot // Global: error.vue at root level with clearError({ redirect: "/" }) ``` `createError` works in both server and client. `NuxtErrorBoundary` isolates component failures. Root `error.vue` catches unhandled errors. See [examples/core.md](examples/core.md) for error page and boundary examples. --- **Detailed Resources:** - [examples/core.md](examples/core.md) - Routing, layouts, error handling, auto-imports - [examples/data-fetching.md](examples/data-fetching.md) - useFetch, useAsyncData, $fetch patterns - [examples/server-routes.md](examples/server-routes.md) - API routes, validation, server middleware - [examples/middleware.md](examples/middleware.md) - Auth guards, role-based access, global middleware - [examples/state-management.md](examples/state-management.md) - useState composables, persistence - [reference.md](reference.md) - Decision frameworks, checklists, anti-patterns --- ## RED FLAGS **High Priority Issues:** - Using `$fetch` directly in `