Should I upgrade to Nuxt 4 to Nuxt 5 Compatibility Version now?
Decide whether to opt into compatibilityVersion 5 now to absorb Nuxt 5 default changes incrementally, or defer and take a larger breaking-change jump later.
Blockers
- Requires framework/nuxt-4 4.2+
- Opting into compatibilityVersion 5 flips the Vite Environment API default early and Nuxt documents medium migration impact.
- Opting into compatibilityVersion 5 changes callHook to non-async behavior.
- Opting into compatibilityVersion 5 enables normalized page component names.
- The roadmap says Nuxt 5 will follow with Nitro v3 and additional changes.
Who this is for
- small-team
- monorepo
- low-ops
Candidates
Opt into future.compatibilityVersion 5 now on Nuxt 4.x
As of 2026-04-04, Nuxt's official upgrade guide says Nuxt 5 is still in development, but many Nuxt 5 breaking changes can already be tested from Nuxt 4.2+ by setting "future.compatibilityVersion: 5". As of 2026-04-04, the official GitHub releases page lists Nuxt v4.4.2 as the latest release. Opting in now flips several defaults early, including the Vite Environment API, normalized page component names, "clearNuxtState" resetting to initial values, non-async "callHook", and comment-node SSR placeholders for client-only components. The official docs also warn that this section is still subject to change until Nuxt 5 is finally released.
When to choose
Use this when you want to spread migration work across normal release cycles and you can actively test your app plus custom modules on each Nuxt 4 update. The decisive factor is whether your team is ready to treat compatibilityVersion 5 as an ongoing migration track rather than a one-time upgrade.
Tradeoffs
You reduce the size of the eventual Nuxt 5 jump and surface breakages earlier, but you accept churn because the Nuxt 5 compatibility section is not final yet. This is strongest for teams with CI coverage and some tolerance for repeated migration follow-up.
Cautions
The biggest blocker is Vite Environment API fallout: Nuxt documents medium migration impact, deprecates environment-specific "extendViteConfig()" usage, and changes how single-environment Vite plugins behave. Also audit any code or modules using ".then()" or ".catch()" on "callHook", any "<KeepAlive>" logic depending on page component names, and any client-only placeholders that relied on an SSR "<div>" for layout.
Stay on compatibilityVersion 4 until Nuxt 5 is closer to final
As of 2026-04-04, Nuxt's roadmap says Nuxt 4 is the stability-focused release line and that Nuxt 5 will follow with Nitro v3 and additional changes. The official upgrade guide explicitly says the Nuxt 5 compatibility section is subject to change until final release, so deferring keeps production behavior on the stable Nuxt 4 default set. This avoids early exposure to moving-target defaults like the Vite Environment API migration and changing runtime semantics. The cost is that more migration work accumulates into the eventual Nuxt 5 project.
When to choose
Use this when stability is more important than incremental migration, especially for small teams, module-heavy apps, or repos with weak upgrade test coverage. The decisive factor is whether avoiding migration churn now is worth a larger concentrated upgrade later.
Tradeoffs
You minimize short-term disruption and avoid adopting defaults that may still shift before Nuxt 5 GA, but you preserve more breaking changes for one later cutover. This can turn the future Nuxt 5 upgrade into a larger test and coordination event.
Cautions
Deferral is safest only if you keep the app current on Nuxt 4 patches and watch the official upgrade guide, because the eventual jump still includes the documented compatibilityVersion 5 changes plus Nuxt 5's Nitro v3 move. Do not assume deferral removes migration work; it mostly postpones it.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to Nuxt 4 to Nuxt 5 Compatibility Version now?"