chore(deps): update dependency nuxt to v4

[renovate]

Coming soon: The Renovate bot (GitHub App) will be renamed to Mend. PRs from Renovate will soon appear from 'Mend'. Learn more here.

This PR contains the following updates:

Package	Change	Age	Confidence
nuxt (source)	^2.14.4 -> ^4.1.2

---

Release Notes

nuxt/nuxt (nuxt)

v4.1.2

Compare Source

4.1.2 is a regularly scheduled patch release.

✅ Upgrading

Our recommendation for upgrading is to run:

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.

👉 Changelog

compare changes

🔥 Performance

• kit: Do not normalise templates in loop if dst is present (#​33200)
• nuxt: Remove watcher from hydrate-when lazy hydration strategy (#​33199)
• nuxt,schema: Normalise components + directories more efficiently (#​33207)
• kit,nuxt: Reduce unnecessary iteration in nuxt code (#​33212)
• nuxt: Skip running lazy hydration transform with filter (#​33213)

🩹 Fixes

• schema: Add pkg-types to dependencies (9fe2541ca)
• nuxt: Ignore errors when treeshaking composables within other composables (f99eac516)
• nuxt: Do not tree-shake composables within other composables (#​33153)
• kit: Ensure module dependencies are typed correctly (4568e8451)
• nuxt: Prevent Infinity backgroundSize in loading indicator (#​33211)
• nuxt: Remove unused enabled from components dir options (#​32844)
• nuxt: Sync watch request in useAsyncData (#​33192)
• nuxt: Move key imports logic after all modules run (#​33214)

📖 Documentation

• Update reference to source dir (65712297a)
• Update language on bridge head migration (c9d986889)
• Update file path for pinia store (#​33205)
• Add app/ suffix to a few links (#​33217)

🏡 Chore

• Dedupe lockfile (d054c90d9)
• Suppress htmlnano type error (ff2e77809)
• nuxt: Unpin tinyglobby (b9ec6507b)

✅ Tests

• Update bundle size test (4d9feb00d)

❤️ Contributors

• Julien Huang (@​huang-julien)
• Daniel Roe (@​danielroe)
• Adrien Foulon (@​Tofandel)
• Matej Černý (@​cernymatej)
• Антон Стасюк (@​11Alone11)
• wuiyang (@​wuiyang)
• Revadike (@​Revadike)

v4.1.1

Compare Source

v4.1.1 is a regularly scheduled patch release

✅ Upgrading

Our recommendation for upgrading is to run:

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.

👉 Changelog

compare changes

🩹 Fixes

• nuxt: Correct relative path of auto imported components (#​33122)
• nuxt: Prefer accessing globalThis over window (#​33125)
• nuxt: Migrate to AST-aware tree-shaking + route injection (#​33128)
• nuxt: Ignore #components import mapping inside packages that use it internally (#​33049)
• vite: Remove explicit vite-node configuration of deps.inline (#​33133)
• nuxt: Include trace in dev-time useRoute usage warning (#​33039)
• kit: Improve DX by displaying module name when possible (#​33137)
• nuxt: Print route middleware path in warning (#​33136)
• nuxt: Include core auto-imports from imports:sources in override warning (#​33050)
• nuxt: Render relative importmap entry path if required (#​33146)

📖 Documentation

• Add -- to bun create command (5e661f0ca)
• Add app/ prefix in lots of cases (#​33117)
• Add JSDoc for navigateTo (#​21442)

🏡 Chore

• Correct rou3 github url (#​33130)
• Include .ts extension (db9d840e1)
• Build before releasing (25f9282a4)

🤖 CI

• Remove default discord reactions from thread (more noise than it's worth) (183913fe2)
• Rewrite release workflow in ts + support multiple tags (4469ead82)
• Pass correct flag (711037cda)
• Pass tag via env variable (fb83cd5ba)
• Drop 4x tags from releases (1cd8a6857)

❤️ Contributors

• Daniel Roe (@​danielroe)
• Matej Černý (@​cernymatej)
• Bobbie Goede (@​BobbieGoede)
• Sébastien Chopin (@​atinux)
• Octavio Araiza (@​8ctavio)
• Michael Brevard (@​GalacticHypernova)
• abeer0 (@​iiio2)
• 山吹色御守 (@​KazariEX)

v4.1.0

Compare Source

👀 Highlights

🔥 Build and Performance Improvements

🍫 Enhanced Chunk Stability

Build stability has been significantly improved with import maps (#​33075). This prevents cascading hash changes that could invalidate large portions of your build when small changes are made:

<!-- Automatically injected import map -->
<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>

By default, JS chunks emitted in a Vite build are hashed, which means they can be cached immutably. However, this can cause a significant issue: a change to a single component can cause every hash to be invalidated, massively increasing the chance of 404s.

In short:

1. a component is changed slightly - the hash of its JS chunk changes
2. the page which uses the component has to be updated to reference the new file name
3. the entry now has its hash changed because it dynamically imports the page
4. every other file which imports the entry has its hash changed because the entry file name is changed

Obviously this wasn't optimal. With this new feature, the hash of (otherwise) unchanged files which import the entry won't be affected.

This feature is automatically enabled and helps maintain better cache efficiency in production. It does require native import map support, but Nuxt will automatically disable it if you have configured vite.build.target to include a browser that doesn't support import maps.

And of course you can disable it if needed:

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false
  }
})

🦀 Experimental Rolldown Support

Nuxt now includes experimental support for rolldown-vite (#​31812), bringing Rust-powered bundling for potentially faster builds.

To try Rolldown in your Nuxt project, you need to override Vite with the rolldown-powered version since Vite is a dependency of Nuxt. Add the following to your package.json:

npm:

{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}

pnpm:

{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@latest"
    }
  }
}

yarn:

{
  "resolutions": {
    "vite": "npm:rolldown-vite@latest"
  }
}

bun:

{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}

After adding the override, reinstall your dependencies. Nuxt will automatically detect when Rolldown is available and adjust its build configuration accordingly.

For more details on Rolldown integration, see the Vite Rolldown guide.

[!NOTE]
This is experimental and may have some limitations, but offers a glimpse into the future of high-performance bundling in Nuxt.

🧪 Improved Lazy Hydration

Lazy hydration macros now work without auto-imports (#​33037), making them more reliable when component auto-discovery is disabled:

<script setup>
// Works even with components: false
const LazyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./MyComponent.vue')
)
</script>

This ensures that components that are not "discovered" through Nuxt (e.g., because components is set to false in the config) can still be used in lazy hydration macros.

📄 Enhanced Page Rules

If you have enabled experimental extraction of route rules, these are now exposed on a dedicated rules property on NuxtPage objects (#​32897), making them more accessible to modules and improving the overall architecture:

// In your module
nuxt.hook('pages:extend', pages => {
  pages.push({
    path: '/api-docs',
    rules: { 
      prerender: true,
      cors: true,
      headers: { 'Cache-Control': 's-maxage=31536000' }
    }
  })
})

The defineRouteRules function continues to work exactly as before, but now provides better integration possibilities for modules.

🚀 Module Development Enhancements

🪾 Module Dependencies and Integration

Modules can now specify dependencies and modify options for other modules (#​33063). This enables better module integration and ensures proper setup order:

export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    'some-module': {
      // You can specify a version constraint for the module
      version: '>=2',
      // By default moduleDependencies will be added to the list of modules 
      // to be installed by Nuxt unless `optional` is set.
      optional: true,
      // Any configuration that should override `nuxt.options`.
      overrides: {},
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`.
      defaults: {}
    }
  },
  setup (options, nuxt) {
    // Your module setup logic
  }
})

This replaces the deprecated installModule function and provides a more robust way to handle module dependencies with version constraints and configuration merging.

🪝 Module Lifecycle Hooks

Module authors now have access to two new lifecycle hooks: onInstall and onUpgrade (#​32397). These hooks allow modules to perform additional setup steps when first installed or when upgraded to a new version:

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    version: '1.0.0',
  },

  onInstall(nuxt) {
    // This will be run when the module is first installed
    console.log('Setting up my-module for the first time!')
  },

  onUpgrade(inlineOptions, nuxt, previousVersion) {
    // This will be run when the module is upgraded
    console.log(`Upgrading my-module from v${previousVersion}`)
  }
})

The hooks are only triggered when both name and version are provided in the module metadata. Nuxt uses the .nuxtrc file internally to track module versions and trigger the appropriate hooks. (If you haven't come across it before, the .nuxtrc file should be committed to version control.)

[!TIP]
This means module authors can begin implementing their own 'setup wizards' to provide a better experience when some setup is required after installing a module.

🙈 Enhanced File Resolution

The new ignore option for resolveFiles (#​32858) allows module authors to exclude specific files based on glob patterns:

// Resolve all .vue files except test files
const files = await resolveFiles(srcDir, '**/*.vue', {
  ignore: ['**/*.test.vue', '**/__tests__/**']
})

📂 Layer Directories Utility

A new getLayerDirectories utility (#​33098) provides a clean interface for accessing layer directories without directly accessing private APIs:

import { getLayerDirectories } from '@​nuxt/kit'

const layerDirs = await getLayerDirectories(nuxt)
// Access key directories:
// layerDirs.app        - /app/ by default
// layerDirs.appPages   - /app/pages by default
// layerDirs.server     - /server by default
// layerDirs.public     - /public by default

✨ Developer Experience Improvements

🎱 Simplified Kit Utilities

Several kit utilities have been improved for better developer experience:

• addServerImports now supports single imports (#​32289):

// Before: required array
addServerImports([{ from: 'my-package', name: 'myUtility' }])

// Now: can pass directly
addServerImports({ from: 'my-package', name: 'myUtility' })

🔥 Performance Optimizations

This release includes several internal performance optimizations:

• Improved route rules cache management (#​32877)
• Optimized app manifest watching (#​32880)
• Better TypeScript processing for page metadata (#​32920)

🐛 Notable Fixes

• Improved useFetch hook typing (#​32891)
• Better handling of TypeScript expressions in page metadata (#​32902, #​32914)
• Enhanced route matching and synchronization (#​32899)
• Reduced verbosity of Vue server warnings in development (#​33018)
• Better handling of relative time calculations in <NuxtTime> (#​32893)

✅ Upgrading

As usual, our recommendation for upgrading is to run:

npx nuxt upgrade --dedupe

This will refresh your lockfile and pull in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

👉 Changelog

compare changes

🚀 Enhancements

• kit: Add ignore option to resolveFiles (#​32858)
• kit: Add onInstall and onUpgrade module hooks (#​32397)
• nuxt,vite: Add experimental support for rolldown-vite (#​31812)
• nuxt: Extract defineRouteRules to page rules property (#​32897)
• nuxt,vite: Use importmap to increase chunk stability (#​33075)
• nuxt: Lazy hydration macros without auto-imports (#​33037)
• kit,nuxt,schema: Allow modules to specify dependencies (#​33063)
• kit,nuxt: Add getLayerDirectories util and refactor to use it (#​33098)

🔥 Performance

• nuxt: Clear inline route rules cache when pages change (#​32877)
• nuxt: Stop watching app manifest once a change has been detected (#​32880)

🩹 Fixes

• nuxt: Handle satisfies in page augmentation (#​32902)
• nuxt: Type response in useFetch hooks (#​32891)
• nuxt: Add TS parenthesis and as expression for page meta extraction (#​32914)
• nuxt: Use correct unit thresholds for relative time (#​32893)
• nuxt: Handle uncached current build manifests (#​32913)
• kit: Resolve directories in resolvePath and normalize file extensions (#​32857)
• schema,vite: Bump requestTimeout + allow configuration (#​32874)
• nuxt: Deep merge extracted route meta (#​32887)
• nuxt: Do not expose app components until fully resolved (#​32993)
• kit: Only exclude node_modules/ if no custom srcDir (#​32987)
• nuxt: Transform ts before page meta extraction (#​32920)
• nuxt: Compare final matched routes when syncing route object (#​32899)
• nuxt: Make vue server warnings much less verbose in dev mode (#​33018)
• schema: Allow disabling cssnano/autoprefixer postcss plugins (#​33016)
• kit: Ensure local layers are prioritised alphabetically (#​33030)
• kit,nuxt: Expose global types to vue compiler (#​33026)
• deps: Bump devalue (#​33072)
• nuxt: Support config type inference for defineNuxtModule().with() (#​33081)
• nuxt: Search for colliding names in route children (b58c139d2)
• nuxt: Delete nuxtApp._runningTransition on resolve (#​33025)
• nuxt: Add validation for nuxt island reviver key (#​33069)

💅 Refactors

• nuxt: Simplify page segment parsing (#​32901)
• nuxt: Remove unnecessary async/await in afterEach (#​32999)
• vite: Simplify inline chunk iteration (6f4da1b8c)
• kit,nuxt,ui-templates,vite: Address deprecations + improve regexp perf (#​33093)

📖 Documentation

• Switch example to use vitest projects (#​32863)
• Update testing setupTimeout and add teardownTimeout (#​32868)
• Update webRoot to use new app directory (df7177bff)
• Add middleware to layers guide (6fc25ff79)
• Use app/ directory in layer guide (eee55ea41)
• Add documentation for --nightly command (#​32907)
• Update package information in roadmap section (#​32881)
• Add more info about nuxt spa loader element attributes (#​32871)
• Update features.inlineStyles default value (6ff3fbebb)
• Correct filename in example (#​33000)
• Add more information about using useRoute and accessing route in middleware (#​33004)
• Avoid variable shadowing in locale example (#​33031)
• Add documentation for module lifecycle hooks (#​33115)

🏡 Chore

• config: Migrate renovate config (#​32861)
• Remove stray test file (ca84285cc)
• Ignore webpagetest.org when scanning links (6c974f0be)
• Add type: 'module' in playground (#​33099)

✅ Tests

• Add failing test for link component duplication (#​32792)
• Simplify module hook tests (#​32950)
• Refactor stubbing of import.meta.dev (#​33023)
• Use findWorkspaceDir rather than relative paths to repo root (a6dec5bd9)
• Improve router test for global transitions (5d783662c)
• Use expect.poll (53fb61d5d)
• Use expect.poll instead of expectWithPolling (357492ca7)
• Use vi.waitUntil instead of custom retry logic (611e66a47)

🤖 CI

• Remove double set of tests for docs prs (6bc9dccf4)
• Add workflow for discord team discussion threads (bc656a24d)
• Fix some syntax issues with discord + github integrations (f5f01b8c1)
• Use token for adding issue to project (66afbe0a2)
• Use discord bot to create thread automatically (618a3cd40)
• Only use discord bot (bfd30d8ce)
• Update format of discord message (eb79a2f07)
• Try bolding entire line (c66124d7b)
• Oops (38644b933)
• Add delay after adding each reaction (ecb49019f)
• Use last lts node version for testing (e06e37d02)
• Try npm trusted publisher (85f1e05eb)
• Use npm trusted publisher for main releases (abf5d9e9f)
• Change wording (#​32979)
• Add github ai moderator (#​33077)

❤️ Contributors

• Daniel Roe (@​danielroe)
• abeer0 (@​iiio2)
• Julien Huang (@​huang-julien)
• kyumoon (@​kyumoon)
• Alexander Lichter (@​TheAlexLichter)
• Bobbie Goede (@​BobbieGoede)
• Rich Harris (@​Rich-Harris)
• mustafa60x (@​mustafa60x)
• Matej Černý (@​cernymatej)
• Alex Liu (@​Mini-ghost)
• Amitav Chris Mostafa (@​semibroiled)
• Romain Hamel (@​romhml)
• Jacky Lam (@​jackylamhk)
• Mukund Shah (@​mukundshah)
• Luke Nelson (@​luc122c)
• letianpailove (@​letianpailove)
• Erwan Jugand (@​erwanjugand)
• Alexander (@​TheColorman)
• Ryota Watanabe (@​wattanx)
• Yizack Rangel (@​Yizack)

v4.0.3

Compare Source

4.0.3 is a regularly scheduled patch release.

👉 Changelog

compare changes

🔥 Performance

• kit: Get absolute path from tinyglobby in resolveFiles (#​32846)

🩹 Fixes

• nuxt: Do not throw undefined error variable (#​32807)
• vite: Include tsconfig references during typeCheck (#​32835)
• nuxt: Add sourcemap path transformation for client builds (#​32313)
• nuxt: Add warning for lazy-hydration missing prefix (#​32832)
• nuxt: Trigger call once navigation even when no suspense (#​32827)
• webpack: Handle null result from webpack call (84816d8a1)
• kit,nuxt: Use reverseResolveAlias for better errors (#​32853)

📖 Documentation

• Fix publicDir alias (#​32841)
• Mention bun.lock for lockfile (#​32820)
• Add a section about augmenting types with TS project references (#​32843)
• Improve explanation of global middleware (#​32855)

🏡 Chore

• Update reproduction help text links (#​32803)
• Update pnpm ignored build scripts (#​32849)
• Improve internal types (052b98a35)

✅ Tests

• Move tests for defineNuxtComponent out of e2e test (#​32848)

🤖 CI

• Move nightly releases into different concurrency group (664041be7)

❤️ Contributors

• RDistinct (@​RDistinct)
• Daniel Roe (@​danielroe)
• Oskar Lebuda (@​OskarLebuda)
• Peter Budai (@​peterbud)
• Matej Černý (@​cernymatej)
• Damian Głowala (@​DamianGlowala)
• Bobbie Goede (@​BobbieGoede)
• Robin (@​OrbisK)
• abeer0 (@​iiio2)
• Julien Huang (@​huang-julien)

v4.0.2

Compare Source

4.0.2 is the next patch release.

Timetable: 28 July.

👉 Changelog

compare changes

🩹 Fixes

• nuxt: Provide typed slots for <ClientOnly> and <DevOnly> (#​32707)
• kit,nuxt,schema: Add trailing slash to some dir aliases (#​32755)
• nuxt: Constrain global defineAppConfig type (#​32760)
• kit: Include module types in app context (#​32758)
• nuxt: Include source base url for remote islands (#​32772)
• vite: Use vite node server to transform requests (#​32791)
• kit: Use mlly to parse module paths (#​32386)
• nuxt: Execute all plugins after error rendering error.vue (#​32744)

📖 Documentation

• Update Nuxt installation command to use npm create nuxt@latest (#​32726)
• Add AI-assisted contribution guidelines (#​32725)
• Hydration best practice (#​32746)
• Add example for module .with() (#​32757)
• Replace dead Vue Router docs links (#​32779)
• Update nightly version references (#​32776)

🏡 Chore

• Update reproduction links for bug-report template (#​32722)
• Update unbuild and use absolute path in dev stubs (#​32759)

✅ Tests

• Ignore vue module.exports export (c4317e057)

🤖 CI

• Release pkg.pr.new for main/3.x branches as well (b0f289550)
• Apply 3x tag to latest v3 release (5f6c27509)

❤️ Contributors

• Daniel Roe (@​danielroe)
• Bobbie Goede (@​BobbieGoede)
• Damian Głowala (@​DamianGlowala)
• Bobby (@​xanzhu)
• Dog (@​dgxo)
• Julien Huang (@​huang-julien)
• Stephen Jason Wang (@​stephenjason89)
• Mateleo (@​Mateleo)
• Robin (@​OrbisK)
• Alex Liu (@​Mini-ghost)

v4.0.1

Compare Source

v4.0.1 is the first regularly scheduled patch release of v4

It will be followed up later this week with v3.18, which will backport a number of the features/fixes from Nuxt v4 to v3.

✅ Upgrading

Our recommendation for upgrading is to run:

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.

👉 Changelog

compare changes

🩹 Fixes

• nuxt: Add nuxt.schema files to node tsconfig context (#​32644)
• nuxt,vite: Unpin nitropack (ed5ad64ad)
• nuxt: Expose shared aliases within shared/ dir (#​32676)

💅 Refactors

• nuxt: Pass file language directly to parser options (#​32665)

📖 Documentation

• Remove rc tag in guide (232b14e2f)
• Remove -t v4 tag from getting started (343f59235)
• Added new Shared folder to the example of v4 folder structure (#​32630)
• Update nuxt.new links to v4 (#​32639)
• Improve grammar (#​32640)
• Typos (#​32567)
• Fix abbreviation (#​32613)
• Reference noUncheckedIndexedAccess rule change in v4 guide (#​32643)
• Add missing import in alias config example (#​32648)
• Correct alias for local fonts in styling guide (#​32680)
• Add best practices section (#​31609)
• Fix links to Nitro docs (#​32691)

📦 Build

• vite: Specify nitropack types as external (39be1b3a9)

🏡 Chore

• Handle missing commit details (5018ed23a)

🤖 CI

• Trigger website redeploy on main branch (#​32695)

❤️ Contributors

• Julien Huang (@​huang-julien)
• Alois Sečkár (@​AloisSeckar)
• Hashim Kalam (@​hashimkalam)
• Daniel Roe (@​danielroe)
• Matej Černý (@​cernymatej)
• Peter Buglavecz (@​buglavecz)
• Haythem Frikha (@​Flamenate)
• abeer0 (@​iiio2)
• Damian Głowala (@​DamianGlowala)
• Robin (@​OrbisK)
• Thomas (@​ThomasWT)

v4.0.0

Compare Source

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:

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:

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:

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)

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.25%. Comparing base (0ce171d) to head (8de8318).

❗ Current head 8de8318 differs from pull request most recent head f30629b

Please upload reports for the commit f30629b to get more accurate results.

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #17   +/-   ##
=======================================
  Coverage   81.25%   81.25%           
=======================================
  Files           2        2           
  Lines          16       16           
  Branches        3        3           
=======================================
  Hits           13       13           
  Misses          2        2           
  Partials        1        1           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.