Nuxt 4 is an evolution, not a rewrite. It keeps the Nuxt 3 mental model but tightens project structure, data-fetching behaviour, and TypeScript. Here are the ten differences that actually change how you write code.
1. New project structure
Nuxt 4 moves app-related folders (components/, composables/, pages/, layouts/, plugins/, etc.) into a dedicated app/ directory, while server/, shared/ and config stay at the project root. The result is a clearer split between client and server worlds.
2. Better separation between app and server code
The boundary between the Vue app and the Nitro server is now explicit and easier to type separately, which prevents server-only code from leaking into the client bundle.
3. A real shared/ directory
Code that must run in both the app and the server — types, constants, pure utilities — lives in shared/. It is not auto-imported by default, so you import it explicitly and avoid accidental coupling.
4. Data-fetching behaviour changed
useAsyncData and useFetch now share refs when you call them with the same key. Calling with the same key returns the same cached data instead of conflicting requests.
5. data and error default to undefined
Previously they initialised to null; in Nuxt 4 they default to undefined. Update any strict === null checks accordingly.
6. pending is more accurate
status and pending now reflect the request lifecycle more precisely, so loading states no longer flash false before a request truly starts.
7. Data is now shallow reactive
Fetched data is shallow-reactive by default. Replace the whole object to trigger an update rather than mutating deep nested properties in place — this is faster and more predictable.
8. TypeScript is stricter
Nuxt 4 generates separate TypeScript configs for the app, server, and shared/build contexts, giving you sharper types and catching cross-context mistakes earlier.
9. A Nuxt 3 compatibility path exists
You can opt into Nuxt 4 behaviour from Nuxt 3 — and ease the migration — via future.compatibilityVersion, so most projects move over with very few behavioural changes.
10. Nuxt 4 is the active stable line
Nuxt 4 is the current stable, actively developed version with new features and performance work. Nuxt 3 has moved into maintenance — bug fixes and security patches only.
Summary: cleaner structure, better separation of concerns, more accurate data handling, and stronger types. Upgrade with confidence.
