hjemmesidekongen/nuxt-patterns

Nuxt Patterns

Architecture

Nuxt 3 is a full-stack Vue framework built on Nitro (server engine) and Vite (dev server). It unifies SSR, SSG, and SPA in one model. The key mental shift from Nuxt 2: everything is composable-first, auto-imported, and TypeScript-native by default.

Directory roles: pages/ → file-based routing, components/ → auto-imported Vue components, composables/ → auto-imported composables, server/api/ → Nitro API routes, server/middleware/ → server-side middleware, layers/ → composable feature layers.

Auto-Imports

Nuxt auto-imports from components/, composables/, utils/, and Nuxt's own API surface. No import statements needed for ref, computed, useState, useFetch, useRoute, defineEventHandler, etc.

Rule: if you're writing import { useFetch } from '#app' or import { ref } from 'vue', you're doing it wrong. Remove the import — it just works.

Custom composables in composables/ are auto-imported by filename. useMyThing.ts → useMyThing() available everywhere.

Data Fetching Decision Tree

Three primitives, each with a specific role:

| Scenario | Use | |----------|-----| | Page-level data, SSR + client hydration | useFetch | | Same data across multiple components | useAsyncData with a shared key | | Client-only fetch (post-mount, no SSR) | $fetch in onMounted or event handler | | Form submissions, mutations | $fetch directly |

useFetch is shorthand for useAsyncData(url, () => $fetch(url)). Use useFetch for the simple case; reach for useAsyncData when you need a custom fetcher, shared deduplication key, or lazy loading.

Caching: both useFetch and useAsyncData deduplicate by key — same key across components shares one request. Pass { key: 'my-key' } explicitly when the URL isn't unique enough.

Server Routes

Defined in server/api/ and server/routes/. server/api/ routes are auto-prefixed with /api/.

Each file exports a default defineEventHandler. Method routing via filename: users.get.ts, users.post.ts. Dynamic params: users/[id].get.ts.

Input validation belongs in the handler — use readBody, getQuery, getRouterParam, then validate before touching the DB.

Full patterns, layers, module development, runtime config, state management, Nuxt 2→3 migration, and anti-patterns: references/process.md