lidge-jun/nuxt4-patterns

Nuxt 4 Patterns

Nuxt 3 EOL: July 31, 2026. Migrate to Nuxt 4 before that date to continue receiving security patches.

Use when building or debugging Nuxt 4 apps with SSR, hybrid rendering, route rules, or page-level data fetching.

When to Activate

• Hydration mismatches between server HTML and client state
• Route-level rendering decisions such as prerender, SWR, ISR, or client-only sections
• Performance work around lazy loading, lazy hydration, or payload size
• Page or component data fetching with useFetch, useAsyncData, or $fetch
• Nuxt routing issues tied to route params, middleware, or SSR/client differences

Directory Structure (Nuxt 4 app/ convention)

Nuxt 4 moves application source into an app/ directory, cleanly separating app code from project config:

project-root/
├── app/                  # Application source (Nuxt 4 default)
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── layouts/
│   ├── middleware/
│   ├── pages/
│   ├── plugins/
│   └── app.vue
├── public/
├── server/               # Server routes & API (stays at root)
├── shared/               # Code shared between app/ and server/
├── nuxt.config.ts
└── package.json

The shared/ directory is for utilities, types, and constants used by both client and server code.

Hydration Safety

• Keep the first render deterministic. Do not put Date.now(), Math.random(), browser-only APIs, or storage reads directly into SSR-rendered template state.
• Move browser-only logic behind onMounted(), import.meta.client, ClientOnly, or a .client.vue component when the server cannot produce the same markup.
• Use Nuxt's useRoute() composable, not the one from vue-router.
• Do not use route.fullPath to drive SSR-rendered markup. URL fragments are client-only, which can create hydration mismatches.
• Treat ssr: false as an escape hatch for truly browser-only areas, not a default fix for mismatches.

Data Fetching

• Prefer await useFetch() for SSR-safe API reads in pages and components. It forwards server-fetched data into the Nuxt payload and avoids a second fetch on hydration.
• Use useAsyncData() when the fetcher is not a simple $fetch() call, when you need a custom key, or when you are composing multiple async sources.
• Give useAsyncData() a stable key for cache reuse and predictable refresh behavior.
• Keep useAsyncData() handlers side-effect free. They can run during SSR and hydration.
• Use $fetch() for user-triggered writes or client-only actions, not top-level page data that should be hydrated from SSR.
• Use lazy: true, useLazyFetch(), or useLazyAsyncData() for non-critical data that should not block navigation. Handle status === 'pending' in the UI.
• Use server: false only for data that is not needed for SEO or the first paint.
• Trim payload size with pick and prefer shallower payloads when deep reactivity is unnecessary.

const route = useRoute()

const { data: article, status, error, refresh } = await useAsyncData(
  () => `article:${route.params.slug}`,
  () => $fetch(`/api/articles/${route.params.slug}`),
)

const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
  lazy: true,
  server: false,
})

Custom useFetch Factories

Create typed, preconfigured fetch composables to reduce boilerplate and enforce API conventions:

// composables/useApiFetch.ts
export function useApiFetch<T>(path: string, opts: Parameters<typeof useFetch>[1] = {}) {
  return useFetch<T>(path, {
    baseURL: '/api',
    headers: { 'X-App-Version': useRuntimeConfig().public.appVersion },
    ...opts,
  })
}

This keeps auth headers, base URLs, and error handling consistent across all data-fetching calls.

Vue Router v5 Features

Nuxt 4 ships with Vue Router v5, which adds:

• Typed route names and params: useRoute('users-id') gives typed params.id without manual casting.
• useRouteQuery: A reactive composable for reading and writing query parameters.
• Route groups: Organize pages by feature with (group)/ directory names — the group name is stripped from the URL.
• Nested lazy routes: Fine-grained control over code-splitting for nested layouts.

Prefer the Nuxt useRoute() / useRouter() composables which wrap Vue Router v5 with SSR-safe behavior.

Route Rules

Prefer routeRules in nuxt.config.ts for rendering and caching strategy:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/products/**': { swr: 3600 },
    '/blog/**': { isr: true },
    '/admin/**': { ssr: false },
    '/api/**': { cache: { maxAge: 60 * 60 } },
  },
})

• prerender: static HTML at build time
• swr: serve cached content and revalidate in the background
• isr: incremental static regeneration on supported platforms
• ssr: false: client-rendered route
• cache or redirect: Nitro-level response behavior

Pick route rules per route group, not globally. Marketing pages, catalogs, dashboards, and APIs usually need different strategies.

Lazy Loading and Performance

• Nuxt already code-splits pages by route. Keep route boundaries meaningful before micro-optimizing component splits.
• Use the Lazy prefix to dynamically import non-critical components.
• Conditionally render lazy components with v-if so the chunk is not loaded until the UI actually needs it.
• Use lazy hydration for below-the-fold or non-critical interactive UI.

<template>
  <LazyRecommendations v-if="showRecommendations" />
  <LazyProductGallery hydrate-on-visible />
</template>

• For custom strategies, use defineLazyHydrationComponent() with a visibility or idle strategy.
• Nuxt lazy hydration works on single-file components. Passing new props to a lazily hydrated component will trigger hydration immediately.
• Use NuxtLink for internal navigation so Nuxt can prefetch route components and generated payloads.

Accessibility (Nuxt 4.4+)

• <NuxtRouteAnnouncer>: Built-in component that announces route changes to screen readers. Included by default in Nuxt 4.4+ app templates.
• useRouteAnnouncer: Composable to customize announcement text on navigation.
• Run npx nuxi module add @nuxtjs/a11y for additional compile-time and runtime accessibility auditing.

Review Checklist

• First SSR render and hydrated client render produce the same markup
• Page data uses useFetch or useAsyncData, not top-level $fetch
• Non-critical data is lazy and has explicit loading UI
• Route rules match the page's SEO and freshness requirements
• Heavy interactive islands are lazy-loaded or lazily hydrated
• App source lives in app/ directory (Nuxt 4 convention)