●Change8

Migrating to Nuxt v4.0.0-alpha.1

Version v4.0.0-alpha.1 introduces 9 breaking changes. This guide details how to update your code.

Released: 6/2/2025

9
Breaking Changes
5
Migration Steps
12
Affected Symbols

⚠️ Check Your Code

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

builder:watchasyncDatarender:htmlcompatibilityVersionglobalName__NUXT__useScriptCrispresolvePathtryResolveModulerequireModuletryRequireModuleClientOnly

Breaking Changes

●Issue #1

Default compatibilityVersion is now set to 4.

●Issue #2

Dropped support for Nuxt 2 and Nuxt Bridge projects.

●Issue #3

Removed old experimental options and the globalName property.

●Issue #4

The __NUXT__ object is now removed from the DOM after hydration.

●Issue #5

The builder:watch hook now emits absolute paths instead of relative ones.

●Issue #6

Vite dev bundler configuration is no longer allowed.

●Issue #7

render:html is no longer called for server islands to improve performance.

●Issue #8

Improved default asyncData value behavior which may change how initial data is handled.

●Issue #9

Internal majorVersion bumped to 4.

Migration Steps

  1. 1
    Enable compatibility mode as described in the Nuxt upgrade guide.
  2. 2
    Update project configuration to support compatibilityVersion: 4.
  3. 3
    Ensure any custom hooks using builder:watch are updated to handle absolute paths.
  4. 4
    Remove any usage of the deprecated globalName property or old experimental options.
  5. 5
    Check for reliance on the __NUXT__ object post-hydration as it is now removed.

Release Summary

Nuxt 4.0.0-alpha.1 is the first early-testing release of Nuxt 4, featuring Nitropack v3 support, Vite 6 integration, and the removal of legacy Nuxt 2 compatibility.

Need More Details?

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

View Full Changelog