Compare Nuxt versions and see exactly what changes, what requires action, and what you can start using.
UpgradePath detects relevant tools and selects them automatically.
Select the tools in your project to include relevant dependency updates in this guide.
Nuxt 4.0.0 requires Node.js ^20.19.0 or >=22.12.0. Historical Nuxt 3 runtime support does not carry over.
{ "engines": { "node": ">=18" } }{ "engines": { "node": "^20.19.0 || >=22.12.0" } }Update development, CI and production runtimes. Use a currently supported Node.js release satisfying the engine range.
The deprecated boolean overload for refresh dedupe no longer works: true maps to cancel and false maps to defer.
await refresh({ dedupe: true })
await refresh({ dedupe: false })await refresh({ dedupe: 'cancel' })
await refresh({ dedupe: 'defer' })Use the explicit string behavior and test concurrent refresh requests.
Unhead 2 removes vmid, hid, children, body and Promise inputs. Legacy configuration can lose tags or fail type checks.
useHead({
script: [{ src: '/analytics.js', body: true }],
meta: [{ hid: 'description', name: 'description', content: 'Guide' }]
})useHead({
script: [{ src: '/analytics.js', tagPosition: 'bodyClose' }],
meta: [{ name: 'description', content: 'Guide' }]
})Use supported tag properties and tagPosition for body tags. Resolve promises before calling useHead.
The duplicate route.meta.name/path fields are no longer populated by Nuxt.
const name = route.meta.name
const path = route.meta.pathconst name = route.name
const path = route.pathRead route.name and route.path directly and review custom route extensions.
Legacy top-level generate.routes/exclude options are removed.
export default defineNuxtConfig({
generate: { routes: ['/about'], exclude: ['/admin'] }
})export default defineNuxtConfig({
nitro: { prerender: { routes: ['/about'], ignore: ['/admin'] } }
})Move route lists to nitro.prerender.routes/ignore. Inspect generated pages, canonical URLs and sitemap links.
Code that reads the global payload after hydration can fail. Nuxt app payload remains available through the app API.
const data = window.__NUXT__.dataconst data = useNuxtApp().payload.dataUse useNuxtApp().payload in Nuxt context. Review analytics/custom integration code accessing the global.
Nuxt 4 adopts an app directory for application code. server, public, modules and shared remain at project root. Existing layouts are auto-detected for backward compatibility.
pages/
components/
composables/
server/
public/app/pages/
app/components/
app/composables/
server/
public/
shared/Review directory detection and custom aliases/tooling. If adopting app/, move application files and remember ~ points to app while ~~ points to project root.
useAsyncData/useFetch return shallow data refs by default. Nested mutations do not trigger reactive updates as they did with deep refs.
const { data } = await useFetch('/api/profile')
data.value.preferences.theme = 'dark'const { data } = await useFetch('/api/profile', { deep: true })
if (data.value) data.value.preferences.theme = 'dark'Prefer immutable replacement; set deep: true per call when nested mutations are intentional and test dependent views.
Calls with the same useAsyncData key share data/error/status. Handler, deep, transform, pick, getCachedData and default must be consistent.
useAsyncData('users', () => $fetch('/api/users'), { deep: true })
useAsyncData('users', () => $fetch('/api/users'), { deep: false })export const useUsers = () => useAsyncData(
'users', () => $fetch('/api/users'), { deep: false }
)
// All consumers call useUsers().Consolidate a key's options in one composable. Use distinct keys for genuinely different resources/options.
Custom cached-data handlers are invoked for refresh/watch as well as initial fetch. Ignoring the cause can prevent an intended network refresh.
getCachedData: key => cache[key]getCachedData: (key, nuxtApp, ctx) => {
if (ctx.cause === 'refresh:manual' || ctx.cause === 'refresh:hook') return undefined
return cache[key]
}Use the context cause to bypass cached data on explicit refresh and review watch-triggered caching.
The initial empty value changes from null to undefined. Strict null-only checks can fail to recognize unloaded data.
if (data.value === null) {
showPlaceholder()
}if (data.value == null) {
showPlaceholder()
}Review initial defaults and checks; use nullish checks when both null and undefined represent an empty state.
pending is derived from status === pending. With immediate: false it starts false rather than treating idle as pending.
<script setup>
const { pending } = await useFetch('/api/items', { immediate: false })
</script>
<template><p v-if="pending">Not loaded yet</p></template><script setup>
const { status, execute } = await useFetch('/api/items', { immediate: false })
</script>
<template>
<button v-if="status === 'idle'" @click="execute()">Load</button>
<p v-if="status === 'pending'">Loading</p>
</template>Use status to distinguish idle, pending, success and error; explicitly execute deferred requests.
Clearing async data now restores its default factory value instead of always setting data to undefined.
const { data, clear } = await useFetch('/api/items', { default: () => [] })
clear()
// Previously data reset to undefined.const { data, clear } = await useFetch('/api/items', { default: () => [] })
clear()
// data is [] again; test length for an empty list.Update reset logic and placeholder checks if relying on clear to remove a default value.
Payload data may be reused across prerendered pages. A static key for route-dependent content can produce the wrong page data.
const route = useRoute()
const { data } = await useAsyncData('article', () =>
$fetch('/api/articles/' + route.params.slug)
)const route = useRoute()
const key = computed(() => 'article:' + route.params.slug)
const { data } = await useAsyncData(key, () =>
$fetch('/api/articles/' + route.params.slug)
)Make keys identify the resource, including relevant route parameters, and verify prerendered HTML and payloads.
Nuxt error data is parsed rather than exposed as a JSON string. An extra JSON.parse can fail on error pages.
const details = JSON.parse(error.data)const details = error.data
// Validate details before reading properties.Consume error.data directly and validate its shape before rendering.
Nuxt scans page metadata after pages:extend. Metadata declared in pages may overwrite earlier hook changes.
export default defineNuxtConfig({
hooks: { 'pages:extend': pages => {
for (const page of pages) page.meta = { ...page.meta, layout: 'admin' }
} }
})export default defineNuxtConfig({
hooks: { 'pages:resolved': pages => {
for (const page of pages) page.meta = { ...page.meta, layout: 'admin' }
} }
})Use pages:resolved for overrides that must win over definePageMeta and test final routes.