Nuxt 3 to 4 Migration Checker for Modules and Config

Nuxt 3 is past its end of life

Nuxt 3 no longer receives bug fixes or security patches. Nuxt 4 is the active major, and the roadmap commits to supporting it for at least six months after Nuxt 5 ships. The table further down lists the dates and the versions the checklists depend on.

The Nuxt team split the breaking changes on purpose. Nuxt 4 is a stability release that turns on by default what compatibilityVersion: 4 used to opt in to. Nuxt 5 follows with the move to Nitro v3 and further changes. A Nuxt 3 app goes through 4 first, so the checker shows the Nuxt 4 checklist before the Nuxt 5 preview.

What the checker reads

The checker parses your package.json in the browser and picks out every dependency named like a Nuxt module, plus any other dependency the module list on nuxt.com names. For each one it looks for a declared Nuxt range in three places, in this order:

1. dist/module.json on jsDelivr. A module built with Nuxt's module builder copies its meta.compatibility there. Nuxt checks that range when it loads the module and, when the running version falls outside it, disables the module with a warning in the console.
2. peerDependencies on npm, under nuxt or @nuxt/kit. Some modules declare their range only here.
3. The module's listing on nuxt.com, used only when the package itself says nothing, and labelled as possibly stale. When this page was checked, nuxt.com listed @nuxt/content as >=3.0.0-rc.3, while the module's own module.json declared >=4.1.0 || ^3.19.0.

It reads two versions of each module: the newest one your range allows, and the latest release. When your range leaves Nuxt 4 out but the latest release declares it, the fix is a module upgrade, and the checker says which version.

Your nuxt.config goes through a TypeScript-aware parser, and keys inside $production, $development and $env overrides count as if set at the top level. Only literal values are read, so a value built from a variable shows as … rather than a guess.

A declared range is a claim, not a test

A range such as >=3.0.0 has no upper bound, so it allows Nuxt 4 and Nuxt 5 without naming either. The checker calls that an open range and counts it apart from a range that names the version. Open ranges are common in modules that predate Nuxt 4, and many of them work fine.

The reverse happens too. The roadmap lists Auth Utils, a planned core module, with Nuxt support for 4.x and 5.x, yet the nuxt-auth-utils package declares no range in its module.json or on npm. A module that declares nothing is not a module that fails; it is one you check by hand, in its changelog and its issues.

A range that leaves your target out is the one to act on first, because Nuxt disables a module whose compatibility range does not match the running version. That shows up as missing features and a console warning, not as a failed build.

The Nuxt 4 changes most likely to bite

The guide labels each change with an impact level, and the checklist keeps that order. Most of the data fetching changes sit near the bottom of it, yet they fail quietly at runtime rather than in the build, so check them first.

data and error from useAsyncData and useFetch now start as undefined rather than null:

- if (data.value === null) {
+ if (data.value === undefined) {

data is now a shallowRef, so mutating a nested property no longer updates the page. Replace the whole value, or opt back in where you need it:

const { data } = await useFetch('/api/todos', { deep: true })

Calls that share a key now share one data, error and status, so their options have to agree. The boolean dedupe values on refresh are gone as well:

- await refresh({ dedupe: true })
+ await refresh({ dedupe: 'cancel' })

The new app/ directory is the most visible change, but it is optional: Nuxt detects the old layout and keeps working with it.

Testing Nuxt 5 today

From Nuxt 4.2 you can switch most defaults to Nuxt 5 behaviour with one flag:

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5,
  },
})

The flag covers changes such as case-sensitive routing, typed pages, the Vite Environment API and the Options API compiled out of the client bundle. It changes defaults, so an experimental option you set explicitly can hold on to today's behaviour; the checker flags each one that Nuxt 5 behaviour would change.

From Nuxt 4.6, server code can import its handler and helpers from nuxt/server, so the same file runs on Nitro v2 today and Nitro v3 under Nuxt 5:

import { defineEventHandler, getQuery } from 'nuxt/server'

export default defineEventHandler((event) => {
  const { name } = getQuery<{ name?: string }>(event)
  return { message: `Hello, ${name ?? 'world'}!` }
})

The Nuxt 5 upgrade guide on nuxt.com is still being written as the work lands, so treat the preview checklist as a moving target.

When starting fresh beats migrating

Migrating keeps your history and is usually the right call. Starting again from a Nuxt 4 base makes more sense when the app is small, when several of its modules declare nothing or leave Nuxt 4 out, or when you were going to replace its auth, payments or deployment anyway. Either way, sort out the modules first: one that blocks Nuxt 4 blocks both paths.