Nuxt

Build Vue 3 SSR/SSG applications with proper data fetching, hydration, and server patterns.

openclaw skills install @ivangdavila/nuxt

Nuxt 3 Patterns

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

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

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

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

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

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

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

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 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

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