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 3 rewrites the configuration and build system. CommonJS configuration and legacy buildModules need migration.
module.exports = {
buildModules: ['@nuxtjs/tailwindcss']
}export default defineNuxtConfig({
modules: ['@nuxtjs/tailwindcss']
})Convert the config to ESM. Move compatible modules to modules and verify each module supports Nuxt 3.
Nuxt 3 uses Vue 3 and Vue Router 4. Vue 2 plugins, filters and removed APIs need review; the Options API remains supported.
<template>{{ price | currency }}</template>
<script>
export default { filters: { currency: v => '$' + v } }
</script><script setup>
const props = defineProps({ price: Number })
const formatted = computed(() => '$' + props.price)
</script>
<template>{{ formatted }}</template>Update Vue dependencies together and replace filters with methods or computed values. Check third-party Vue compatibility.
useAsyncData and useFetch transfer server-fetched data through the Nuxt payload. A direct $fetch in component setup can fetch again during hydration.
<script>
export default {
async asyncData({ $axios }) {
return { posts: await $axios.$get('/api/posts') }
}
}
</script><script setup>
const { data: posts, error, status } = await useFetch('/api/posts')
</script>Use useFetch for URLs or useAsyncData for custom handlers. Return serializable data and handle pending/error states.
The context/inject plugin signature is replaced by a Nuxt app plugin. Plugins in plugins/ are registered automatically.
export default (context, inject) => {
inject('hello', name => 'Hello ' + name)
}// plugins/hello.ts
export default defineNuxtPlugin(() => ({
provide: { hello: (name: string) => 'Hello ' + name }
}))
// In component setup:
const { $hello } = useNuxtApp()Return helpers through provide and use useNuxtApp to consume them. Name browser-only plugins with .client.ts.
defineNuxtRouteMiddleware receives to/from rather than Nuxt 2 context. Redirects and aborts must be returned.
export default function ({ store, redirect }) {
if (!store.state.user) return redirect('/login')
}export default defineNuxtRouteMiddleware(() => {
const user = useState('user', () => null)
if (!user.value) return navigateTo('/login')
})Move middleware to the new signature, return navigateTo/abortNavigation and use .global.ts for global route middleware.
Nuxt 2 underscore route conventions change to Vue Router 4-style bracket filenames.
pages/users/_id.vue
pages/_.vuepages/users/[id].vue
pages/[...slug].vueRename dynamic/catch-all files and verify optional parameters, generated routes and direct SSR requests.
The Nuxt 2 Nuxt and NuxtChild components are replaced. Layout and page settings move to definePageMeta.
<!-- layouts/default.vue -->
<template><main><Nuxt /></main></template><!-- layouts/default.vue -->
<template><main><slot /></main></template>
<!-- app.vue -->
<template><NuxtLayout><NuxtPage /></NuxtLayout></template>Use slot in layouts and NuxtPage for pages/nested pages. Wrap the root page in NuxtLayout when using layouts.
publicRuntimeConfig/privateRuntimeConfig become runtimeConfig with a public section. Public values are exposed to the browser.
export default {
privateRuntimeConfig: { apiSecret: '' },
publicRuntimeConfig: { apiBase: '/api' }
}export default defineNuxtConfig({
runtimeConfig: {
apiSecret: '', // NUXT_API_SECRET; server only
public: { apiBase: '/api' } // NUXT_PUBLIC_API_BASE
}
})Keep secrets at the root and read configuration using useRuntimeConfig. Use matching NUXT_ environment variables at runtime.
Nuxt 3 uses the standalone Nitro server with file-based API routes and H3 handlers.
// nuxt.config.js
export default { serverMiddleware: [
{ path: '/api/health', handler: '~/api/health.js' }
] }
// api/health.js
export default (req, res) => res.end('ok')// server/api/health.get.ts
export default defineEventHandler(() => ({ status: 'ok' }))Move Express/connect middleware to compatible Nitro handlers. Preserve authentication, status codes and response semantics.
Node deployments run .output/server/index.mjs. Nuxt 2 nuxt start and .nuxt directory deployment instructions do not match Nitro.
npm run build
npx nuxt startnpm run build
node .output/server/index.mjsBuild for the intended Nitro preset and ship the complete .output. Check SSR pages, environment values, static assets and health endpoints.
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 3 uses Unhead. useHead/useSeoMeta support reactive SSR metadata; duplicate-tag identifiers such as hid are unnecessary.
<script>
export default {
head: () => ({ meta: [{ hid: 'description', name: 'description', content: 'Upgrade guide' }] })
}
</script><script setup>
useSeoMeta({ title: 'Upgrade guide', description: 'Upgrade guide' })
useHead({ link: [{ rel: 'canonical', href: 'https://example.com/guide' }] })
</script>Migrate page titles, descriptions and canonical links, then inspect server HTML. Do not expose server-only values in metadata.
Nuxt 3 has no built-in Vuex integration. useState creates shared SSR-safe state; module-scope refs can leak state between server requests.
// Shared across requests when imported by server code:
export const user = ref(null)// Call from component setup or a Nuxt composable:
export const useUser = () => useState('user', () => null)Migrate small state to useState or install compatible Pinia integration. Keep user-specific state inside Nuxt request context.
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.