●Change8

Migrating to Nuxt v4.0.0

Version v4.0.0 introduces 5 breaking changes. This guide details how to update your code.

Released: 7/15/2025

5
Breaking Changes
5
Migration Steps
5
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

useAsyncDatauseFetch@nuxt/kit@nuxt/clitsconfig.json

Breaking Changes

●Issue #1

New default project structure: Application code now resides in the 'app/' directory by default. Existing structures are still detected but the default has shifted.

●Issue #2

Data fetching defaults: useAsyncData and useFetch now have different default behaviors regarding data sharing and cleanup.

●Issue #3

TypeScript project separation: Nuxt now creates separate TS projects for app, server, shared, and builder contexts, which may surface new type errors.

●Issue #4

Nuxt 2 compatibility removed from @nuxt/kit, affecting module authors.

●Issue #5

Removal of legacy utilities and deprecated features from previous versions.

Migration Steps

  1. 1
    Read the official Nuxt 4 upgrade guide.
  2. 2
    Run 'npx nuxt upgrade --dedupe' to update dependencies and deduplicate the lockfile.
  3. 3
    Optional: Run 'npx codemod@latest nuxt/4/migration-recipe' to automate code changes.
  4. 4
    Review TypeScript errors surfaced by the new project-based separation.
  5. 5
    Verify module compatibility and update any modules that do not yet support Nuxt 4.

Release Summary

Nuxt 4 is a stability-focused major release introducing a new 'app/' directory structure, improved TypeScript context separation, and a faster socket-based CLI. It streamlines the data fetching layer while providing a smooth migration path for Nuxt 3 projects.

Need More Details?

View the full release notes and all changes for Nuxt v4.0.0.

View Full Changelog