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