Nuxt4 Patterns

1---2name: nuxt4-patterns3description: Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData.4origin: ECC5---6 7# Nuxt 4 Patterns8 9Use when building or debugging Nuxt 4 apps with SSR, hybrid rendering, route rules, or page-level data fetching.10 11## When to Activate12 13- Hydration mismatches between server HTML and client state14- Route-level rendering decisions such as prerender, SWR, ISR, or client-only sections15- Performance work around lazy loading, lazy hydration, or payload size16- Page or component data fetching with `useFetch`, `useAsyncData`, or `$fetch`17- Nuxt routing issues tied to route params, middleware, or SSR/client differences18 19## Hydration Safety20 21- Keep the first render deterministic. Do not put `Date.now()`, `Math.random()`, browser-only APIs, or storage reads directly into SSR-rendered template state.22- Move browser-only logic behind `onMounted()`, `import.meta.client`, `ClientOnly`, or a `.client.vue` component when the server cannot produce the same markup.23- Use Nuxt's `useRoute()` composable, not the one from `vue-router`.24- Do not use `route.fullPath` to drive SSR-rendered markup. URL fragments are client-only, which can create hydration mismatches.25- Treat `ssr: false` as an escape hatch for truly browser-only areas, not a default fix for mismatches.26 27## Data Fetching28 29- 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.30- 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.31- Give `useAsyncData()` a stable key for cache reuse and predictable refresh behavior.32- Keep `useAsyncData()` handlers side-effect free. They can run during SSR and hydration.33- Use `$fetch()` for user-triggered writes or client-only actions, not top-level page data that should be hydrated from SSR.34- Use `lazy: true`, `useLazyFetch()`, or `useLazyAsyncData()` for non-critical data that should not block navigation. Handle `status === 'pending'` in the UI.35- Use `server: false` only for data that is not needed for SEO or the first paint.36- Trim payload size with `pick` and prefer shallower payloads when deep reactivity is unnecessary.37 38```ts39const route = useRoute()40 41const { data: article, status, error, refresh } = await useAsyncData(42  () => `article:${route.params.slug}`,43  () => $fetch(`/api/articles/${route.params.slug}`),44)45 46const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {47  lazy: true,48  server: false,49})50```51 52## Route Rules53 54Prefer `routeRules` in `nuxt.config.ts` for rendering and caching strategy:55 56```ts57export default defineNuxtConfig({58  routeRules: {59    '/': { prerender: true },60    '/products/**': { swr: 3600 },61    '/blog/**': { isr: true },62    '/admin/**': { ssr: false },63    '/api/**': { cache: { maxAge: 60 * 60 } },64  },65})66```67 68- `prerender`: static HTML at build time69- `swr`: serve cached content and revalidate in the background70- `isr`: incremental static regeneration on supported platforms71- `ssr: false`: client-rendered route72- `cache` or `redirect`: Nitro-level response behavior73 74Pick route rules per route group, not globally. Marketing pages, catalogs, dashboards, and APIs usually need different strategies.75 76## Lazy Loading and Performance77 78- Nuxt already code-splits pages by route. Keep route boundaries meaningful before micro-optimizing component splits.79- Use the `Lazy` prefix to dynamically import non-critical components.80- Conditionally render lazy components with `v-if` so the chunk is not loaded until the UI actually needs it.81- Use lazy hydration for below-the-fold or non-critical interactive UI.82 83```vue84<template>85  <LazyRecommendations v-if="showRecommendations" />86  <LazyProductGallery hydrate-on-visible />87</template>88```89 90- For custom strategies, use `defineLazyHydrationComponent()` with a visibility or idle strategy.91- Nuxt lazy hydration works on single-file components. Passing new props to a lazily hydrated component will trigger hydration immediately.92- Use `NuxtLink` for internal navigation so Nuxt can prefetch route components and generated payloads.93 94## Review Checklist95 96- First SSR render and hydrated client render produce the same markup97- Page data uses `useFetch` or `useAsyncData`, not top-level `$fetch`98- Non-critical data is lazy and has explicit loading UI99- Route rules match the page's SEO and freshness requirements100- Heavy interactive islands are lazy-loaded or lazily hydrated