Nuxt 4 Guide: What Changed and How to Migrate from Nuxt 3

Nuxt 4 is the latest stable version of the framework, and if you are on Nuxt 3 the upgrade is smaller than a major version number usually suggests. Most of what changed is about structure and defaults, not a rewrite: a new app/ directory for your source code, a more consistent data-fetching layer, and tighter TypeScript project boundaries.

This guide covers what actually changed from Nuxt 3, then walks you through migrating an existing app step by step. If you just want to upgrade, jump to the migration checklist. If you want to understand what you are signing up for first, start with the what-changed table below.

What changed from Nuxt 3 to Nuxt 4

This table describes changes between the version starting with the most impactful, exciting, or potentially breaking and moves to more minor concerns.

The changes mentioned in the table above are some of the most impactful and not exhaustive but will cover the use cases of most users. To find an exhaustive list, visit the official migration guide.

Step-by-step migration checklist (Nuxt 3 → Nuxt 4)

1. Read the official upgrade guide and pin the target version. Note the exact Nuxt 4 release you are upgrading to and its minimum Node.js version (verify the required Node LTS).
2. Bump Node if needed. Match the Node version Nuxt 4 requires before touching anything else.
3. Run the official upgrade command. Note that you may need to use nuxi@latest to ensure a version with support for the channel flag.

npx nuxi@latest upgrade --dedupe --channel=v3

1. Run the official migration codemod. Nuxt ships an automated migration recipe that moves files into app/ and applies known fixes to breaking changes.

npx codemod nuxt/4/migration-recipe

1. Confirm the new layout by hand. App code under app/; server/, public/, modules/, and content directories still at the root. Fix anything the codemod missed.
2. Update paths, aliases, and config. Check custom srcDir or directory overrides and any hardcoded paths that assumed the old root layout. Verify how ~ and @ aliases resolve under the new structure.
3. Audit data fetching. Find components that share a useAsyncData / useFetch key, and any code that mutated fetched data in place or leaned on deep reactivity. Adjust for the shared, deduplicated data layer.
4. Move shared code into shared/. Relocate utilities and types used by both client and server.
5. Benefit from the new TS contexts. Create the TS files, for the app, server, node, and shared contexts. You can copy/paste these from a newly created Nuxt 4 project.
6. Update your modules. Bump each Nuxt module to a Nuxt 4 compatible version and verify one by one; a lagging module is the most common upgrade blocker.
7. Build, test, and smoke-test SSR. Run the full test suite, do a production build, and manually check SSR and hydration on your highest-traffic pages.

Should you upgrade now?

1. Already on Nuxt 3?

Upgrading is worth doing and, for most apps, quick. The structural changes are mechanical and the codemod handles the bulk of them. Turn on compatibility mode first (step 3) so you can adopt the new defaults gradually instead of in one risky jump.

1. Starting a new project?

Begin on Nuxt 4 directly and use the app/ structure from day one. The TS experience is much better and dev server startup much faster on Windows!

1. On a large app with many modules?

The upgrade itself is small, but your dependencies gate it. Before scheduling the work, confirm your critical modules have Nuxt 4 compatible releases.

1. Still on Nuxt 2 or Bridge?

Nuxt 2 reached end of life on 2024-06-30 and it’s imperative you make the switch but it is a much bigger jump. Migrate to Nuxt 3 first, then follow this checklist.

Nuxt 4 Frequently Asked Questions (FAQ)

1. Is Nuxt 4 a big rewrite or a hard upgrade?

No. It is an evolution of Nuxt 3. Most of the change is the new app/ directory and updated data-fetching defaults, and an automated codemod handles the file moves. Many apps upgrade in an afternoon.

1. Do I have to use the new app/ directory?

The app/ layout is the new default and the recommended structure. You can keep the old layout (Nuxt will auto-detect it), but prefer adopting the new structure for anything long-lived (it’s an easy switch anyways).

1. Can I try the Nuxt 4 changes before upgrading?

Yes. In Nuxt 3, set future: { compatibilityVersion: 4 } in nuxt.config. That opts you into the Nuxt 4 defaults so you can find and fix breakages while still on Nuxt 3.

1. What usually breaks when upgrading to Nuxt 4?

Three things most often: incompatible modules, paths and config that assumed the old root layout, and code that relied on the old data-fetching reactivity or on components holding independent copies of the same fetch. Running the codemod in an app with a robust test suite catches most of it.

1. What changed with data fetching in Nuxt 4?

   • Singleton data fetching layer (Moderate)
   • Calls with the same key now share the same data, error, and status refs.
   • Calls with an explicit key must not have conflicting deep, transform, pick, getCachedData, or default options (this now triggers a warning).
   • getCachedData is now called on every fetch, including watcher-triggered fetches and refreshNuxtData (previously skipped in those cases).
   • getCachedData now receives a context object with ctx.cause ('initial' | 'refresh:hook' | 'refresh:manual' | 'watch').
   • Reactive keys (computed refs, plain refs, or getter functions) are now supported and trigger automatic refetching.
   • Data is purged from memory when the last component using it unmounts.
   • Opt out via experimental.granularCachedData: false and experimental.purgeCachedData: false.

   Shared prerender data (Medium)

   • Payload data from useAsyncData/useFetch is now shared across prerendered pages.
   • You must ensure each unique key always resolves to the same data (e.g. include dynamic route params in the key).
   • Opt out via experimental.sharedPrerenderData: false.

   Default data and error values (Minimal)

   • data and error now default to undefined instead of null; update any null checks.
   • Opt out via experimental.defaults.useAsyncData: { value: 'null', errorValue: 'null' }.

   dedupe boolean removal (Minimal)

   • refresh({ dedupe: true }) must become refresh({ dedupe: 'cancel' }).
   • refresh({ dedupe: false }) must become refresh({ dedupe: 'defer' }).

   Respect defaults when clearing (Minimal)

   • clear/clearNuxtData now resets data to your custom default value rather than unsetting it.
   • Opt out via experimental.resetAsyncDataToUndefined: true.

   pending alignment (Medium)

   • pending is now a computed property that's true only when status is 'pending'.
   • With immediate: false, pending stays false until the first request (previously always true).
   • Opt out via experimental.pendingWhenIdle: true.

   Key-change behavior (Medium)

   • useFetch now matches useAsyncData: with immediate: false, a key change only refetches if data was already fetched once.
   • With immediate: false, you must call refresh/execute manually the first time.
   • Opt out via experimental.alwaysRunFetchOnKeyChange: true.

   Shallow data reactivity (Minimal)

   • data is now a shallowRef, so mutating a property within the object no longer triggers reactivity (replacing the whole object still does).
   • Opt back into deep reactivity per-call with { deep: true }, or globally via experimental.defaults.useAsyncData: { deep: true }.

Conclusion

Nuxt 4 includes some great quality of life improvements with an easy upgrade story that most teams complete in a day or so. To get a first hand glance at the improvements and how they benefit you, I recommend checking out our course What’s New in Nuxt 4 where we we walk you through the most impactful changes step by step via video. New to Vue and Nuxt in general? Checkout the most comprehensive course around on the subject: the the Vue 3 MasterClass or it’s Nuxt specific counter-part: Mastering Nuxt.