Nuxt fundamentals explained

What Nuxt is (and how it extends Vue)

Vue is a UI library. Nuxt is a meta-framework that wires Vue into a complete application shell:

• Routing — files in pages/ become routes automatically (like Next.js App Router or Remix file routes).
• Rendering — the same components render on the server for HTML-first delivery or pre-render at build time.
• Data layer — useFetch runs on server during SSR and hydrates on the client without duplicate requests.
• Backend — server/api/ and server/routes/ define HTTP handlers compiled by Nitro to Node, serverless, or edge workers.
• Tooling — Vite for dev HMR, TypeScript path aliases, and a module ecosystem for auth, CMS, and image optimization.

Nuxt 3 (current major version) replaced the webpack-based Nuxt 2 build with Vite and Nitro. If you know Vue 3 Composition API and <script setup>, Nuxt adds conventions — not a second component model. Teams already on plain Vue + Vite often adopt Nuxt when they need SSR, API colocation, or SEO without assembling five libraries manually.

Core directories

Rendering modes and route rules

Nuxt defaults to universal SSR: the server renders HTML with data, the client hydrates and takes over navigation. You can override per route or globally:

• SSR (default) — dynamic HTML per request; best for authenticated dashboards and frequently changing data.
• SSG / prerender — nuxt generate or routeRules: { '/blog/**': { prerender: true } } emits static HTML at build time; ideal for marketing and docs.
• SPA — ssr: false in config ships a client-only bundle; use when SEO does not matter and deploy is purely static CDN.
• ISR / SWR — routeRules with swr: 3600 caches server responses and revalidates in the background (Nitro storage or CDN integration).
• Hybrid — public catalog pages prerendered, /account/** SSR with cookies; one app, different rules per path prefix.

routeRules in nuxt.config.ts is the modern replacement for scattering generate.routes lists. Pair prerendered marketing pages with SSR app shells the way teams split Next.js marketing vs app routes — but without two repositories.

Data fetching: useFetch and useAsyncData

The most common Nuxt mistake is calling fetch in onMounted after SSR already ran empty. Nuxt’s composables coordinate server and client:

• useFetch('/api/shipments') — wraps $fetch (ofetch); deduplicates identical keys; serializes result into the HTML payload for hydration.
• useAsyncData('shipments', () => $fetch(...)) — lower-level; you supply a stable key and async function; use when transforming data or combining multiple sources.
• $fetch — universal fetch helper; on server can call internal Nitro routes directly without HTTP loopback.
• refresh() / clear() — returned from composables to re-run queries after mutations.

During SSR, useFetch awaits on the server and embeds JSON in window.__NUXT__ (payload). On client navigation, Nuxt reuses cached data when the key matches and optionally revalidates. Set lazy: true to render the page shell immediately and load data after mount — similar to React Suspense boundaries.

When to fetch where

Nitro server routes and runtime config

Nitro is Nuxt’s server engine. Files in server/ compile to a standalone server or serverless functions:

// server/api/shipments/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const row = await db.shipment.findUnique({ where: { id } })
  if (!row) throw createError({ statusCode: 404, message: 'Not found' })
  return row
})

Handlers use defineEventHandler with Web Standard event objects. HTTP method suffixes (.get.ts, .post.ts) map to verbs. server/middleware/ runs on every request (logging, CORS). server/plugins/ hooks Nitro startup (database connection pools).

Runtime config separates public from private env vars:

• runtimeConfig.public.apiBase — exposed to client via useRuntimeConfig()
• runtimeConfig.dbUrl — server-only; never serialized to the browser

Map NUXT_DB_URL and NUXT_PUBLIC_API_BASE environment variables at deploy time. Nitro presets target Node (node-server), Vercel, Netlify, Cloudflare Workers, Deno, and static hosting with optional serverless API routes.

Modules, middleware, and auto-imports

Nuxt modules extend config at build time. Common choices:

• @nuxtjs/tailwindcss — Tailwind v4 integration; pairs with our Tailwind fundamentals guide.
• @pinia/nuxt — client state stores; use for UI toggles, not server data cache.
• @nuxt/image — responsive images with lazy loading and CDN providers.
• @nuxt/content — Markdown/MDC content layer for docs and blogs.
• nuxt-auth-utils or custom session middleware — cookie sessions on Nitro.

Route middleware (middleware/auth.ts) runs before page navigation. Return navigateTo('/login') to redirect. definePageMeta({ middleware: 'auth' }) applies per page. Server middleware differs: it guards API routes before handlers execute.

Auto-imports mean ref, computed, useRoute, and your composables/useTracking.ts need no import statements. Disable selectively if tree-shaking surprises you, but most teams embrace the ergonomics.

Worked example: Harbor Fleet cargo tracker

Harbor Fleet ships a customer-facing cargo tracker on Nuxt 3 with the Node Nitro preset behind nginx. The design optimizes for SEO on public tracking pages and fast CSR navigations inside the ops dashboard:

• Route tree: pages/index.vue (marketing hero) → pages/track/[bl].vue (bill-of-lading lookup, SSR) → pages/dashboard/shipments/index.vue (auth-gated list) → pages/dashboard/shipments/[id].vue (detail + timeline).
• Public track page: useFetch(`/api/public/track/${bl}`) runs on server; meta tags set via useSeoMeta({ title: () => `Shipment ${bl}` }) for Google snippets.
• API layer: server/api/public/track/[bl].get.ts queries read replica; strips internal cost fields before JSON response.
• Dashboard auth: middleware/auth.ts reads sealed session cookie; server middleware on /api/dashboard/** double-checks role claims.
• Live updates: detail page opens EventSource to /api/dashboard/shipments/[id]/events (Nitro streaming) for milestone pushes; falls back to 30s polling.
• Rendering rules: routeRules: { '/': { prerender: true }, '/track/**': { swr: 60 }, '/dashboard/**': { ssr: true } }.
• Mutations: status notes POST to server/api/dashboard/shipments/[id]/notes.post.ts; client calls refresh() on the detail useAsyncData key after success.

Tests call Nitro handlers with await $fetch('/api/...', { headers }) in Vitest without launching a browser. One Playwright path covers BL lookup end-to-end. The pattern mirrors our Remix guide (loaders + actions) but stays in Vue templates and composables throughout.

Framework decision table

Versus Remix: both colocate server data with UI. Nuxt centers Vue and Nitro; Remix centers React and Web Standard loaders/actions. Versus SvelteKit: similar meta-framework shape; choose based on team language preference and component library availability.

Common pitfalls

• Fetching in onMounted for SSR pages — users see empty shell then flash; use useFetch or useAsyncData at top level.
• Exposing secrets via runtimeConfig — only keys under public are safe; database URLs belong in private config accessed server-side only.
• Non-unique useAsyncData keys — colliding keys share cache across unrelated pages; include route params in the key string.
• Importing server-only modules in components — bundles blow up or leak secrets; keep db imports in server/ handlers only.
• Disabling SSR globally for one client bug — ssr: false trades away SEO and first paint; fix hydration mismatch instead.
• Pinia as API cache — duplicates useFetch invalidation; use Pinia for UI state, composables for remote data.
• Ignoring payload size — serializing huge lists into SSR payload slows TTFB; paginate server responses.

Production checklist

• Scaffold with npx nuxi@latest init; enable TypeScript and ESLint module from day one.
• Define routeRules per section (prerender, SSR, SWR) instead of one global mode.
• All initial page data via useFetch/useAsyncData; mutations call refresh() or optimistic local state.
• Server handlers validate input with Zod; return createError for 4xx/5xx consistently.
• Runtime config documented in .env.example; secrets injected at deploy, never committed.
• Nitro preset matches host (Node vs serverless); health check at /api/health bypasses heavy deps.
• useSeoMeta and canonical URLs on public routes; test with view-source, not only client render.
• Vitest tests for composables and server handlers; Playwright smoke on critical flows.
• nginx or CDN caches static .output/public assets with fingerprinted filenames.
• Monitor hydration errors in production logging; mismatches indicate SSR/client divergence.

Key takeaways

• Nuxt 3 unifies Vue 3, Vite, and Nitro into one full-stack framework with file-based conventions.
• useFetch and useAsyncData bridge SSR and client navigation without duplicate network calls.
• server/api handlers colocate backend logic; runtime config keeps secrets server-side.
• routeRules mix prerendered marketing, cached public pages, and dynamic SSR dashboards.
• Choose Nuxt when Vue is the UI layer and you need SEO, BFF APIs, and hybrid rendering in one repo.

Related reading

• Vue.js fundamentals explained — reactivity, Composition API, and single-file components
• Next.js fundamentals explained — the React full-stack counterpart
• Vite fundamentals explained — dev server, HMR, and build pipeline under Nuxt
• SSR, CSR, SSG, and ISR explained — rendering modes and when each fits