Nuxt 4 Migration: The Breaking Changes That Actually Bite

Nuxt 3 reached end-of-life on July 31, 2026. No more security patches, no more bug fixes, no more compatibility updates — ever, for that line. If your package.json still says "nuxt": "^3", you're not behind on a nice-to-have; you're running unmaintained software in production. And the first time you run npm install nuxt@latest to fix that, something you didn't touch will break in a way the error message doesn't explain.

This article is written against Nuxt 4.6.0 (verified against the nuxt package's npm dist-tags in October 2026 — the 3x tag is frozen at 3.21.11, a patch that actually shipped August 5, 2026, five days after the cutoff; the last release before the cutoff itself was 3.21.10, on July 27, 2026). It walks through what the official Nuxt 4 release notes and upgrade guide actually say breaks, why those specific things were chosen to break, and the staged path that lets you fix each one without a single big-bang rewrite.

By the end of this article you'll be able to:

You have a Nuxt 3 app in production, or you're planning a new one and want to know what "Nuxt 4" actually changes before you commit to it. You don't need prior Nitro or Nuxt-internals knowledge — just familiarity with useAsyncData/useFetch and a standard nuxt.config.ts.

Here's the instinct that gets people in trouble: Nuxt 3 minor versions have been safe to bump for years, so nuxt@4 looks like just the next number in the same sequence. A team runs the upgrade on a Friday afternoon, the dev server boots, the homepage renders, and it ships.

Monday morning, two unrelated bugs show up:

The guest banner stops appearing for logged-out users on first paint. Nobody touched useAsyncData. Nobody touched the banner component. The bug is two features away from the code that actually changed, because data now defaults to undefined, not null — and undefined === null is false.

That's the shape of almost every Nuxt 4 migration bug: not a loud crash, a quiet behavioral default that moved. The fix for all of them is the same shape too — know the list, grep for it, fix it deliberately — which is what the rest of this article gives you.

The mental model: every headline Nuxt 4 change is Nuxt drawing a boundary it used to leave implicit, and then enforcing it. Nuxt 3 inferred almost everything from one root directory and a lot of convention; Nuxt 4 makes several of those conventions into contracts that tooling — the file watcher, the TypeScript project, the data layer — can actually rely on.

Once you see it that way, the "random" list of breaking changes stops being random:

Read every section below through that lens: what boundary is this enforcing, and what breaks when my code quietly depended on that boundary being fuzzy?

Nuxt 4's advertised headline change is that application code — components/, pages/, layouts/, app.vue — lives under app/ by default, while public/, shared/, server/, and nuxt.config.ts stay at the project root:

Key concept: if your project already has this shape (most Nuxt 3 starters from the last year or two already do), nothing changes — Nuxt detects the existing layout and keeps it working. This is the part of the migration that generates the most noise online and causes the least real breakage.

Two situations where it does bite:

If you do want to adopt the new layout, Nuxt ships a codemod rather than asking you to move files by hand:

Moving files is optional. Everything else in this article is not.

This is the change most teams don't see coming, because it looks like useAsyncData just works differently now rather than looking like a documented breaking change.

In Nuxt 3, two useAsyncData/useFetch calls that happened to share a key were already treated as "the same fetch" in practice — the previous episode in this series covers exactly that sharing behavior and the auto-key bug it causes. Nuxt 4 takes that same-key-means-same-fetch idea and makes it a hard contract: calls sharing a key now must agree on handler, deep, transform, pick, getCachedData, serialize, default, and middleware. Mismatch any of them, and Nuxt logs a development-mode warning — but it doesn't block anything, and you still end up with inconsistent state instead of the two independent results you might expect:

The fix: if two call sites legitimately need the same key, move the call into one shared composable so the options live in exactly one place, instead of being copy-pasted (and drifting) at each call site:

The other half of this change is getCachedData. It used to matter mostly on the initial load; in Nuxt 4 it's called on every fetch for that key — including a watch-triggered refetch or a manual refreshNuxtData() — and it receives a cause ('initial' | 'refresh:hook' | 'refresh:manual' | 'watch') so you can decide, per cause, whether to trust the cache:

Two smaller defaults sit next to the data layer change and are easy to miss in a changelog skim:

Both are one-line fixes once you know to look for them. Neither throws an error, which is exactly why they're worth grepping for deliberately rather than waiting for a bug report.

One small removal with a mechanical fix: window.__NUXT__ is removed after hydration completes, where it used to linger. Code reading it post-hydration (analytics scripts, debug snippets) needs to capture what it needs earlier — or read the same payload from useNuxtApp().payload instead, which Nuxt keeps around.

The bigger surprise isn't a removal at all, and it's opt-in rather than automatic: Nuxt 4 generates separate, context-specific TypeScript project references (tsconfig.app.json, tsconfig.server.json, tsconfig.node.json, tsconfig.shared.json) alongside the old merged tsconfig.json, and keeps the old one as the default for backwards compatibility — your existing root tsconfig.json keeps working, unchanged, until you point it at the new files. Once you do (a fresh Nuxt 4 project scaffolds it this way by default, and the migration codemod can set it up for an existing one), nuxt typecheck often jumps from zero errors to a page of them. That's not a new Nuxt 4 bug — each context now gets its own, more accurate globals and includes, so TypeScript can finally see code that was always slightly wrong.

The official guide's real advice isn't "bump the package and fix what breaks" — it's to opt into Nuxt 4 behavior while still on the Nuxt 3 package, so you can fix issues one at a time with a fast feedback loop, before the cutover:

With that flag set, your Nuxt 3 app runs with Nuxt 4's new defaults — the data layer contract, the null/undefined change, the directory resolution — so you see every real breakage in your own code, in your own dev server, without touching your dependency tree yet. Fix what it surfaces, commit, then bump nuxt itself to ^4.0.0 as a final, much smaller step.

Run the migration recipe codemod once you're ready for the mechanical renames (pin the version — @latest has a known issue with this one):

No. Nuxt 4 detects an existing Nuxt 3-style layout and keeps it working without any file moves. Moving to app/ is optional, and a codemod (npx codemod@latest nuxt/4/file-structure) does it for you if you choose to.

Only if two useAsyncData/useFetch calls share a key with mismatched options (transform, deep, pick, getCachedData, serialize, default, middleware, or the handler itself). Nuxt does log a development warning when it detects the mismatch, but it's a warning, not a thrown error — it doesn't stop the build, and the wrong data still ships unless you act on it. Centralizing shared-key calls into one composable removes the whole category of bug.

Yes, but the official guide's recommended path is to first set future.compatibilityVersion: 4 on your current Nuxt 3 app, fix everything it surfaces, and only then bump the nuxt package itself — rather than doing both at once.

They keep running — npm packages don't disappear — but Nuxt 3 no longer receives security patches, bug fixes, or compatibility updates as of July 31, 2026. That risk grows, silently, the longer it's deferred.

Yes, independently of your own code. Nuxt 2/Bridge support is removed from @nuxt/kit, so a module that hasn't been updated for Nuxt 4 may break regardless of anything in this article. Check the module's own changelog before upgrading an app that relies on it.

None of this is mysterious once you have the list — it's a short, specific set of boundaries Nuxt now enforces instead of leaving implicit. Run the compatibility flag, work the list once, and the actual package bump becomes the smallest, most boring step in the whole migration.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

What's the first thing on this list you'd find if you grepped your own app for it right now?

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: