Nuxt 3 Patterns

---
name: nuxt-c95c0a8ee4bf
description: Build Vue 3 SSR/SSG applications with proper data fetching, hydration, and server patterns.
metadata: {"clawdbot":{"emoji":"💚","requires":{"bins":["node"]},"os":["linux","darwin","win32"]}}
---

# Nuxt 3 Patterns

## Data Fetching
- `useFetch` deduplicates and caches requests during SSR — use it in components, not `$fetch` which fetches twice (server + client)
- `$fetch` is for event handlers and server routes only — in `<script setup>` it causes hydration mismatches
- `useFetch` runs on server during SSR — check `process.server` if you need client-only data
- Add `key` option to `useFetch` when URL params change but path stays same — without it, cache returns stale data
- `useLazyFetch` doesn't block navigation — use for non-critical data, but handle the pending state

## Hydration Traps
- `Date.now()` or `Math.random()` in templates cause hydration mismatches — compute once in setup or use `<ClientOnly>`
- Browser-only APIs (localStorage, window) crash SSR — wrap in `onMounted` or `process.client` check
- Conditional rendering based on client-only state mismatches — use `<ClientOnly>` component with fallback
- `v-if` with async data shows flash of wrong content — use `v-show` or skeleton states instead

## Auto-imports
- Components in `components/` auto-import with folder-based naming — `components/UI/Button.vue` becomes `<UIButton>`
- Composables in `composables/` must be named `use*` for auto-import — `utils.ts` exports won't auto-import
- Server utils in `server/utils/` auto-import in server routes only — not available in client code
- Disable auto-imports per-file with `// @ts-nocheck` or explicitly import to avoid naming collisions

## Server Routes
- Files in `server/api/` become API routes — `server/api/users.get.ts` handles GET /api/users
- Method suffix (`.get.ts`, `.post.ts`) is required for method-specific handlers — without it, handles all methods
- `getQuery(event)` for query params, `readBody(event)` for POST body — don't access `event.req` directly
- Return value is auto-serialized to JSON — throw `createError({ statusCode: 404 })` for errors

## State Management
- `useState` is SSR-safe and persists across navigation — regular `ref()` resets on each page
- `useState` key must be unique app-wide — collisions silently share state between components
- Pinia stores need `storeToRefs()` to keep reactivity when destructuring — without it, values lose reactivity
- Don't initialize state with browser APIs in `useState` default — it runs on server too

## Middleware
- Global middleware in `middleware/` with `.global.ts` suffix runs on every route — order is alphabetical
- Route middleware defined in `definePageMeta` runs after global — use for auth checks on specific pages
- `navigateTo()` in middleware must be returned — forgetting `return` continues to the original route
- Server middleware in `server/middleware/` runs on all server requests including API routes

## Configuration
- `runtimeConfig` for server secrets, `runtimeConfig.public` for client-safe values — env vars override with `NUXT_` prefix
- `app.config.ts` for build-time config that doesn't need env vars — it's bundled into the app
- `nuxt.config.ts` changes require restart — `app.config.ts` changes hot-reload

## SEO and Meta
- `useSeoMeta` for standard meta tags — type-safe and handles og:/twitter: prefixes automatically
- `useHead` for custom tags, scripts, and links — more flexible but no type safety for meta names
- Meta in `definePageMeta` is static — use `useSeoMeta` in setup for dynamic values
- `titleTemplate` in `nuxt.config` for consistent titles — `%s - My Site` pattern

## Plugins
- Plugins run before app creation — use `nuxtApp.hook('app:created')` for post-creation logic
- `provide` in plugins makes values available via `useNuxtApp()` — but composables are cleaner
- Plugin order: numbered prefixes (`01.plugin.ts`) run first, then alphabetical — dependencies need explicit ordering
- Client-only plugins: `.client.ts` suffix — server-only: `.server.ts` suffix

## Build and Deploy
- `nuxt generate` creates static files — but API routes won't work without a server
- `nuxt build` creates server bundle — deploy the `.output` directory
- ISR with `routeRules`: `'/blog/**': { isr: 3600 }` — caches pages for 1 hour
- Prerender specific routes: `routeRules: { '/about': { prerender: true } }` — builds static HTML at build time