Nuxt.js Files

Nuxt 4.0 is here! 🎉

After a year of real-world testing, we're excited to announce the official release of Nuxt 4. This is a stability-focused major release, introducing a few thoughtful breaking changes in order to improve development experience.

If you've been following along, you'll recognize many of these features and changes — and if you're new to them, we hope you'll welcome them.

🔥 What's new?

Nuxt 4 is all about making your development experience smoother:

• Cleaner project organization with the new app/ directory structure
• Smarter data fetching - we've taken the opportunity to address some inconsistencies and improve performance with the data layer
• Better TypeScript support with project-based separation between the different contexts in your project - app code, server code, shared/ folder, and configuration
• Faster CLI and development with adoption of internal sockets and a faster CLI

Why these features in particular? Mostly because these kind of improvements have required making changes that are technically breaking.

In general, we aim for a hype-free approach to releases. Rather than save up features for a big release, we've been shipping improvements in Nuxt 3 minor releases.

We've also spent a lot of time figuring out how to implement these changes in a backwards-compatible way, and I hope that means that most Nuxt 3 projects can upgrade with a minimum of effort.

I'd advise reading through the upgrade guide before you start, to understand what areas of your app might be affected.

🗂️ New project structure

The biggest visible change is how projects are organized. Your application code now lives in an app/ directory by default:

:::bash
my-nuxt-app/
├─ app/
│  ├─ components/
│  ├─ pages/
│  ├─ layouts/
│  └─ app.vue
├─ public/
├─ shared/
├─ server/
└─ nuxt.config.ts

This helps keep your code separate from node_modules/ and .git/, which makes file watchers faster (especially on Windows and Linux). It also gives your IDE better context about whether you're working with client or server code.

[!TIP] Don't want to migrate? That's totally fine! Nuxt will detect your existing structure and keep working exactly as before.

🎨 Updated UI templates

Nuxt’s starter templates have an all new look, with improved accessibility, default titles, and template polish (#27843).

🔄 Smarter data fetching

We've made useAsyncData and useFetch work better. Multiple components using the same key now share their data automatically. There's also automatic cleanup when components unmount, and you can use reactive keys to refetch data when needed. Plus, we've given you more control over when cached data gets used.

Some of these features have already been made available in Nuxt v3 minor releases, because we've been rolling this out gradually. Nuxt v4 brings different defaults, and we expect to continue to work on this data layer in the days to come.

🔧 Better TypeScript experience

Nuxt now creates separate TypeScript projects for your app code, server code, shared/ folder, and builder code. This should mean better autocompletion, more accurate type inference and fewer confusing errors when you're working in different contexts.

[!TIP] With Nuxt 4, you will only need one tsconfig.json file in your project root!

This is probably the single issue that is most likely to cause surprises when upgrading, but it should also make your TypeScript experience much smoother in the long run. Please report any issues you encounter. 🙏

⚡ Faster CLI and development

In parallel with the release of v4, we've been working on speeding up @nuxt/cli.

• Faster cold starts - Development server startup is noticeably faster
• Node.js compile cache - Automatic reuse of the v8 compile cache
• Native file watching - Uses fs.watch APIs for fewer system resources
• Socket-based communication - The CLI and Vite dev server now communicate via internal sockets instead of network ports, reducing overhead — particularly on Windows

These improvements combined can make a really noticeable difference in your day-to-day development experience, and we have more planned.

🚀 How to upgrade

Although any major release brings breaking changes, one of our main aims for this release is to ensure that the upgrade path is as smooth as possible. Most of the breaking changes have been testable with a compatibility flag for over a year.

Most projects should upgrade smoothly, but there are a few things to be aware of:

• Nuxt 2 compatibility has been removed from @nuxt/kit. (This will particularly affect module authors.)
• Some legacy utilities and deprecated features have been cleaned up.
• The new TypeScript setup might surface some type issues that were hidden before.
• A few modules might need further updates for full Nuxt 4 compatibility.

Don't worry though — for most breaking changes, there are configuration options to revert to the old behavior while you adjust.

1. Update Nuxt

Our recommendation for upgrading is to run:

:::sh
npx nuxt upgrade --dedupe

This will deduplicate your lockfile as well, and help ensure that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

2. Optional: use migration tools

We’ve also partnered with Codemod to automate many, though not all, migration steps:

:::bash
npx codemod@latest nuxt/4/migration-recipe

3. Test and adjust

Run your tests, check that everything builds correctly, and fix any issues that come up. The upgrade guide has detailed migration steps for specific scenarios.

We'd recommend reading through it in full before starting your upgrade, to understand what areas of your app might be affected.

🗺️ What's next?

We're planning quick patch releases to address any issues that come up. Nuxt 3 will continue to receive maintenance updates (both bug fixes and backports of features from Nuxt 4) until the end of January 2026, so there's no rush if you need time to migrate.

Looking ahead, we plan to release Nuxt 5 on the sooner side, which will bring Nitro v3 and h3 v2 for even better performance, as well as adopting the Vite Environment API for an improved (and faster!) development experience. And there's a lot more in the works too!

And, quite apart from major releases, we have a lot of exciting features planned to make their way into Nuxt 3.x and 4.x release branches, including support for SSR streaming (#4753), a first-party accessibility module (#23255), built-in fetch caching strategies (#26017), more strongly typed fetch calls (landing in Nitro v3), dynamic route discovery (#32196), multi-app support (#21635) and more.

❤️ Thank you

This release is credit to so many people, particularly those who have been testing v4 compatibility mode over the past year. I'm really grateful — thank you for all your help!

Happy coding with Nuxt 4! 🚀

👉 Changelog

compare changes

🚀 Enhancements

• ui-templates: Update template branding for v4 (#27843)
• deps: Upgrade to latest versions of c12, jiti and unbuild (#27995)
• kit: Reimplement cjs utils using mlly (#28012)
• nuxt: Generate basic jsdoc for module config entry (#27689)
• schema: Split dev/prod build directories (#28594)
• nuxt: Cache vue app build outputs (#28726)
• deps: Update dependency vite to v6 (main) (#30042)
• nuxt: Add integration with chrome devtools workspaces (#32084)
• kit: Support single import in addServerImports (#32289)
• nuxt: Add onWatcherCleanup to imports presets (#32396)
• kit,nuxt,schema: Separate ts projects for node/app/nitro (#30665)
• nuxt: Support lazy hydration macros (#31192)
• nuxt: Export <NuxtTime> prop types (#32547)
• nuxt: Add route announcer to default app.vue (#32621)
• nuxt: Expose page routes to nitro for o11y (#32617)

🔥 Performance

• nuxt: ⚠️ Don't call render:html for server islands (#27889)
• vite: Don't write stub manifest for legacy bundler (#27957)
• kit: Update env expansion regex to match nitro (#30766)
• vite: Communicate with vite-node via internal socket (#32417)

🩹 Fixes

• schema,vite: ⚠️ Do not allow configuring vite dev bundler (#27707)
• schema: ⚠️ Default to compatibilityVersion: 4 (#27710)
• nuxt: ⚠️ Emit absolute paths in builder:watch hook (#27709)
• nuxt: ⚠️ Improve default asyncData value behaviour (#27718)
• nuxt: ⚠️ Remove old experimental options (#27749)
• kit: ⚠️ Support loading nuxt 4 and drop support for <=2 (#27837)
• nuxt: ⚠️ Remove __NUXT__ after hydration (#27745)
• ui-templates: Add default title back (3415241a6)
• kit: ⚠️ Drop support for building nuxt 2 projects (1beddba6a)
• nuxt: ⚠️ Bump internal majorVersion to 4 (7aae4033b)
• kit: Mark resolvePath utils as sync (655e1473d)
• kit: Revert change to tryResolveModule (2d136e04c)
• kit: Add back requireModule and tryRequireModule (#28013)
• nuxt: Hide unhandled error messages in prod (#28156)
• nuxt: Add useScriptCrisp scripts stub (0c3cc4cf3)
• nuxt: ⚠️ Remove unused globalName property (#28391)
• nuxt: Use static import for updateAppConfig in HMR (#28349)
• vite: Write dev manifest when ssr: false (#28488)
• kit,nuxt,schema: ⚠️ Remove other support for nuxt2/bridge (#28936)
• webpack: Only insert dynamic require plugin when building (b619b35e9)
• nuxt: Guard window access (d874726ff)
• nuxt: Remove unneeded subpath import (18a6ef1ca)
• webpack: Handle new webpack chunk format (d293c06d2)
• kit: ⚠️ Do not check compatibility for nuxt version < 2.13 (f94cda4c8)
• ui-templates: Fix examples link and add bluesky (#30866)
• vite: Use resolveId from vite-node to resolve deps (#30922)
• nuxt: Import isEqual from main ohash export (3ec1a1e5e)
• vite: Don't set output.preserveModules (ce49734aa)
• nuxt: Ignore #app-manifest import in dev mode (#31539)
• nuxt: Ensure layer array-type config is merged in order (#31507)
• schema: Turn off purgeCachedData until v4 (7aa3a01ae)
• schema: Re-enable purgeCachedData by default (06745604c)
• webpack: Expand dynamic require regexp to match new pattern (62e700daa)
• nuxt: Add back missing reset of .execute (d79e14612)
• nuxt,schema: ⚠️ Remove support for compatibilityVersion: 3 (#32255)
• kit,nuxt,schema,vite: ⚠️ Remove support for some deprecated options (#32257)
• nuxt: ⚠️ Don't rerun asyncdata w/ existing data in useAsyncData (#32170)
• nuxt: Scan nitro handlers before writing types (a3698c08b)
• nuxt: Force asyncData errorValue/value to be undefined (7e4eac655)
• nuxt: ⚠️ Remove public and assets aliases (#32119)
• webpack: Update dynamic require pattern (#32278)
• schema: ⚠️ Remove top level generate option (#32355)
• ui-templates: Add aria tag on Nuxt logo (#32429)
• nuxt: Augment runtime config in server context (#32482)
• kit: Do not skip layer with defined srcDir (#32487)
• deps: Upgrade to rc version of @nuxt/cli (#32488)
• kit: Ensure legacy tsConfig doesn't exclude too many types (#32528)
• kit: Ensure types of module entrypoints are in node project (#32551)
• kit: Add layer app/ and server/ folders into tsconfigs (#32592)
• schema: Disable changing compat version (#32600)
• nuxt: Allow modules to add to typescript.hoist (#32601)
• nuxt: Include shared declarations in tsconfig.server.json (#32594)
• nuxt: Retain old data when computed key changes (#32616)
• nuxt: ⚠️ Bump compatibilityDate to 2025-07-15 (e35e1ccb9)
• nuxt: Only use scrollBehaviorType for hash scrolling (#32622)

💅 Refactors

• kit,nuxt: ⚠️ Drop nuxt 2 + ejs template compile support (#27706)
• nuxt: ⚠️ Move #app/components/layout -> #app/components/nuxt-layout (209e81b60)
• kit,nuxt,vite,webpack: ⚠️ Remove legacy require utils (#28008)
• nuxt: Simplify check of dedupe option (#28151)
• nuxt: Use direct import of installNuxtModule (501ccc375)
• kit: Remove internal function (#32189)
• schema: ⚠️ Remove config.schema.json export + defaults (#32254)
• nuxt: Migrate to oxc-walker (#32250)
• nuxt,schema: Use oxc for onPrehydrate transform (#32045)

📖 Documentation

• Indicate what useAsyncData must return (#28259)
• Update deep default for useAsyncData & useFetch (#28564)
• Fix link to issue (4d13f1027)
• Improve wording for deep option (bec85dfcd)
• Update v4 docs with new folder structure (#32348)
• Update .nuxtignore examples for v4 structure (#32489)
• Add reference to useNuxtData in data fetching composable pages (#32589)
• Temporarily use v4 template for v4 docs (850a879d3)
• Document the --modules flag in the init command (#32599)

📦 Build

• deps: Bump esbuild from 0.23.1 to 0.25.0 (#31247)

🏡 Chore

• Manage update to vite-plugin-checker separately (02d46dd3d)
• Update docs typecheck command (#28433)
• Improve accuracy of 4.x changelog (#28706)
• Bump package versions internally to v4 (16fab7778)
• kit: Fix regressed version v4 (a1c052057)
• Dedupe lockfile (f14ef6bc9)
• Update once more (4d22f4d5a)
• Specify workspace engines.node compatibility (a26322f5f)
• Remove special treatment for typescript (08766a0cd)
• Reenable quarantine for webpack/memfs (for 3.x benefit) (9cb94e55e)
• Remove extra dep (f0ec34298)
• Add back nuxi (9aa4c7c3b)
• Remove stray nuxi version again (#30547)
• Fix lockfile (7d345c714)
• Remove second version of vitest (#30868)
• Ignore oxc-parser updates temporarily (1cd0fb5cb)
• Ignore nitro/templates directory (e531477f8)
• Fix ui-templates build (c8a1b9e80)
• Mkdir for ui-templates (853408a1e)
• Add webpack resolution (088bcd459)
• Migrate playground + test fixtures to new directory format (#32357)
• schema: Remove duplicated documentation (349f75447)

✅ Tests

• Remove unused experimental options (6d971ddc9)
• Add additional attw test for built packages (#30206)
• Add minimal pages fixture (#30457)
• Update bundle size assertion (f458153d9)
• Update bundle size assertion (4cce6bf8d)
• Benchmark minimal fixture instead (#31174)
• Normalise scoped css + pass logger to configResolved (8d3bd4f9f)
• More precise asyncData tests (023fb13eb)
• Extend timeout when waiting for hydration (f34c6c240)
• Also assert status (4f6bdf755)

🤖 CI

• Bump node v22 (#30251)
• Run workflows on merge groups (ff37ad9df)
• Do not invoke semantic-pr test on merge groups (fadd618d1)

⚠️ Breaking Changes

• nuxt: ⚠️ Don't call render:html for server islands (#27889)
• schema,vite: ⚠️ Do not allow configuring vite dev bundler (#27707)
• schema: ⚠️ Default to compatibilityVersion: 4 (#27710)
• nuxt: ⚠️ Emit absolute paths in builder:watch hook (#27709)
• nuxt: ⚠️ Improve default asyncData value behaviour (#27718)
• nuxt: ⚠️ Remove old experimental options (#27749)
• kit: ⚠️ Support loading nuxt 4 and drop support for <=2 (#27837)
• nuxt: ⚠️ Remove __NUXT__ after hydration (#27745)
• kit: ⚠️ Drop support for building nuxt 2 projects (1beddba6a)
• nuxt: ⚠️ Bump internal majorVersion to 4 (7aae4033b)
• nuxt: ⚠️ Remove unused globalName property (#28391)
• kit,nuxt,schema: ⚠️ Remove other support for nuxt2/bridge (#28936)
• kit: ⚠️ Do not check compatibility for nuxt version < 2.13 (f94cda4c8)
• nuxt,schema: ⚠️ Remove support for compatibilityVersion: 3 (#32255)
• kit,nuxt,schema,vite: ⚠️ Remove support for some deprecated options (#32257)
• nuxt: ⚠️ Don't rerun asyncdata w/ existing data in useAsyncData (#32170)
• nuxt: ⚠️ Remove public and assets aliases (#32119)
• schema: ⚠️ Remove top level generate option (#32355)
• nuxt: ⚠️ Bump compatibilityDate to 2025-07-15 (e35e1ccb9)
• kit,nuxt: ⚠️ Drop nuxt 2 + ejs template compile support (#27706)
• nuxt: ⚠️ Move #app/components/layout -> #app/components/nuxt-layout (209e81b60)
• kit,nuxt,vite,webpack: ⚠️ Remove legacy require utils (#28008)
• schema: ⚠️ Remove config.schema.json export + defaults (#32254)

❤️ Contributors

• Daniel Roe (@danielroe)
• Connor Pearson (@cjpearson)
• Stephen Jason Wang (@stephenjason89)
• dwood-csi (@dwood-csi)
• Alex (@hywax)
• Alex Liu (@Mini-ghost)
• Bobbie Goede (@BobbieGoede)
• Marko (@aussieboi)
• Igor Kononenko (@igorexa34314)
• Alexander Lichter (@TheAlexLichter)
• Robin (@OrbisK)
• Matej Černý (@cernymatej)
• Michael Brevard (@GalacticHypernova)
• Andrej Adamcik (@adamcikado)
• dependabot[bot] (@dependabot[bot])
• Sébastien Chopin (@atinux)
• Yauheni Vasiukevich (@EvgenyWas)
• @beer (@iiio2)
• Anthony Fu (@antfu)
• pan93412 (@pan93412)
• Tobias Diez (@tobiasdiez)
• Aleksei Nagovitsyn (@al3xnag)
• xjccc (@xjccc)
• Julien Huang (@huang-julien)