Roadmap to v4

We originally planned Nuxt 4 for June 2024, but things don't always go according to plan. I think it's appropriate to take a different approach:

👉 Nuxt 4 alpha will ship June 2, 2025, with a stable release at the end of the month. Nuxt 5 will come later once Nitro v3 is ready.

Why Two Releases?

Honestly, in hindsight I think we should have shipped Nuxt v4 last year. It would have aligned better with our once-a-year plan for careful major releases.

On the other hand, it has allowed time for testing across countless projects, by opting in to Nuxt 4 breaking changes with a single flag. I think that we should go ahead and ship these changes as Nuxt v4 for two reasons:

1. People are already using it. I frequently hear of teams who are using compatibilityVersion: 4 in production. This option was intended only for testing, but it has proven solid enough for production use. We want to make it official, and give these teams the protection of a stable release.
2. It will improve the migration. Having a two-stage migration from v3 -> v4, and then v4 -> v5 will make for a smoother migration. We don't yet have a final list of breaking changes for Nitro v3, and this means we can spend enough time to ensure that the Nitro upgrade is smooth, while not delaying adoption of the Nuxt changes we've planned for the last year.

What's more, going forward we're going to do our best to decouple Nuxt releases from our key dependencies, like Vite or Nitro.

What's Included?

Nuxt 4 includes all the features you've been testing with compatibilityVersion: 4:

• 🗂️ New Directory Structure - code goes in app/ for cleaner organization and better IDE performance
• 🔄 Improved Data Fetching - smarter useAsyncData and useFetch with better caching and cleanup
• 🏷️ Consistent Component Names - Vue DevTools and <KeepAlive> now see the same names as Nuxt's auto-imports
• 📄 Enhanced Head Management - dropping deprecated features from Unhead v2 with better performance and tag optimization

... as well as many other improvements documented in the upgrade guide. There are also a handful of further changes we will shipping, including:

• preparations for adopting the Vite Environment API (with a single dev server)
• improvements to type 'environment' handling (for server, client, and shared code)

What About Nitro?

We're not delaying Nitro v3 adoption. We aim for Nuxt 5 to arrive with Nitro v3 at the same time we originally planned, even if that's only a few months after the release of Nuxt v4.

Despite the delays over the past year, we've seen phenomenal progress on Nitro. As a whole team, we're very excited to unveil what we have planned in Nitro v3 and h3 v2.

While Nuxt 4 won't initially include these upgrades, releasing Nuxt v4 and Nitro v3 in parallel will mean we can test both Nuxt and Nitro more thoroughly across the ecosystem by the time Nuxt 5 arrives.

What About Nuxt 3?

We'll provide ongoing maintenance and support for Nuxt 3 after the first stable release of Nuxt 4 — and continue supporting both Nuxt 3 and Nuxt 4 after Nuxt 5 has been released. We've intentionally chosen a slightly shorter timetable of six months support for each of these releases because we believe that it will be a straightforward upgrade.

(My main aim for the Nuxt 4 upgrade is to ensure that it is as smooth as possible.)

Nevertheless, I'll be closely monitoring to see how successfully and quickly the ecosystem migrates. If there are issues I will absolutely extend that six month ongoing maintenance window. We don't want to leave anyone behind.

For a while, this will mean active backports of features and bugfixes across three versions. But I think it's worth it. And we have — after all — been doing this for the last year in preparation for Nuxt 4.

What's Next

Today we release Nuxt v4 alpha 1! We'd love early adopters to test it. Please do report issues to Nuxt or any modules that you may be using.

Here's what you can expect over the next few weeks:

• We plan to open upstream PRs for community modules in the nuxt/modules registry, and create a migration guide for module authors.
• We'll create a full upgrade guide for Nuxt 3 users, including a list of breaking changes and how to migrate. (The current upgrade guide explains how to enable compatibility mode, but there are some differences with Nuxt 4.)
• We'll only release bugfixes for v3 this month, deferring backporting new features until after the release of v4.
• We'll update the docs on nuxt.com to allow switching between 3.x, 4.x and (soon) 5.x documentation.
• Once we release the release candidate (we're aiming for June 23) we'd love everyone to dive in again for a last round of testing. We'll only be expecting bugfixes from this point onward.
• Once v4 is released, we'll separate the main branch to 4.x to adopt edge releases of h3 and nitro and begin development of Nuxt 5.

I'm really excited with this timeline — and thank you for your patience and trust over the last year!