chore(deps): update dependency nuxt to v4

[renovate]

This PR contains the following updates:

Package	Change	Age	Confidence
nuxt (source)	^2.15.8 -> ^4.2.0

---

Release Notes

nuxt/nuxt (nuxt)

v4.2.0

Compare Source

4.2.0 is the next minor release.

👀 Highlights

We're excited to announce Nuxt 4.2, bringing new capabilities for better TypeScript DX, enhanced error handling, and improved control over data fetching! 🎉

🎯 Abort Control for Data Fetching

You can now pass an AbortController signal directly to useAsyncData and useFetch, giving you fine-grained control over request cancellation (#​32531).

<script setup lang="ts">
const controller = new AbortController()

const { data, error } = await useAsyncData('users', () => $fetch('/api/users', {
  signal: controller.signal
}))

// Cancel the request manually when needed
function cancelRequest() {
  controller.abort()
}
</script>

This is particularly useful when you need to abort requests based on user actions or component lifecycle events. The abort signal can also be passed to refresh() and execute() methods:

const { data, refresh } = await useAsyncData('posts', fetchPosts)

// Abort an ongoing refresh
const abortController = new AbortController()
refresh({ signal: abortController.signal })

// Later...
abortController.abort()

🎨 Better Error Pages in Development

When an error occurs during development, Nuxt will now display both your custom error page and a detailed technical error overlay (#​33359). This gives you the best of both worlds – you can see what your users will experience while also having immediate access to stack traces and debugging information.

The technical overlay appears as a toggleable panel that doesn't interfere with your custom error page, making it easier to debug issues while maintaining a realistic preview of your error handling.

🔮 Opt-in Vite Environment API

For those wanting to experiment with cutting-edge features, you can now opt into the Vite Environment API (#​33492).

The Vite Environment API is a major architectural improvement in Vite 6. It closes the gap between development and production by allowing the Vite dev server to handle multiple environments concurrently (rather than requiring multiple Vite dev servers, as we have done previously in Nuxt).

This should improve performance when developing and eliminate some edge case bugs.

... and it is the foundation for implementing Nitro as a Vite environment, which should speed up the dev server still further, as well as allowing more greater alignment in development with your Nitro preset.

export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true
  }
})

This is also the first breaking change for Nuxt v5. You can opt in to these breaking changes by setting compatibilityVersion to 5:

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5
  },
})

Please only use this for testing, as this opts in to unlimited future breaking changes, including updating to Nitro v3 once we ship the Nuxt integration.

[!WARNING]
This is highly experimental and the API may change. Only enable if you're prepared for potential breaking changes and want to help shape the future of Nuxt!

📦 New @nuxt/nitro-server Package

We've extracted Nitro server integration into its own package: @nuxt/nitro-server (#​33462). This architectural change allows for different Nitro integration patterns and paves the way for future innovations in server-side rendering.

While this change is mostly internal, it's part of our ongoing effort to make Nuxt more modular and flexible. The new package provides standalone Nitro integration and sets the foundation for alternative integration approaches (such as using Nitro as a Vite plugin in Nuxt v5+).

[!NOTE]
This is an internal refactor – no changes should be required in your code.

⚡ Performance Improvements

We've also shipped several performance enhancements:

• Precomputed renderer dependencies – We now compute renderer dependencies at build time rather than runtime, improving cold start and initial render performance (#​33361)
• Reduced dependencies – Removed unnecessary dependencies from kit and schema packages (7ae2cf563)

📉 Async Data Handler Extraction

One of the most exciting performance improvements is the new experimental async data handler extraction (#​33131). When enabled, handler functions passed to useAsyncData and useLazyAsyncData are automatically extracted into separate chunks and dynamically imported.

This is particularly effective for prerendered static sites, as the data fetching logic is only needed at build time and can be completely excluded from the client bundle.

[!NOTE]
In testing with a previous version of nuxt.com, this feature reduced JavaScript bundle size by 39%! Of course, your mileage may vary depending on how much data fetching logic you have.

<script setup lang="ts">
// This handler will be extracted into a separate chunk
// and only loaded when needed
const { data: post } = await useAsyncData('post', async () => {
  const content = await queryContent(`/blog/${route.params.slug}`).findOne()
  
  // Complex data processing that you don't want in the client bundle
  const processed = await processMarkdown(content)
  const related = await findRelatedPosts(content.tags)
  
  return {
    ...processed,
    related
  }
})
</script>

For static/prerendered sites, enable it in your config:

export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true
  }
})

The extracted handlers are then tree-shaken from your client bundle when prerendering, as the data is already available in the payload. This results in significantly smaller JavaScript files shipped to your users.

🔧 Experimental TypeScript Plugin Support

We're introducing experimental support for enhanced TypeScript developer experience through the @dxup/nuxt module.

This module adds a number of TypeScript plugins that aim to improve your experience when using Nuxt-specific features:

• Smart component renaming: Automatically updates all references when you rename auto-imported component files
• Go to definition for dynamic imports: Navigate directly to files when using glob patterns like import(\~/assets/${name}.webp`)`
• Nitro route navigation: Jump to server route handlers from data fetching functions ($fetch, useFetch, useLazyFetch)
• Runtime config navigation: Go to definition works seamlessly with runtime config properties
• Enhanced auto-import support: Includes the @dxup/unimport plugin for better navigation with auto-imported composables and utilities

[!NOTE]
Read more in the documentation.

To enable this feature, set experimental.typescriptPlugin to true in your Nuxt configuration:

export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true
  }
})

Once enabled, the module will be automatically installed and configured by Nuxt.

[!IMPORTANT]
This feature also requires selecting the workspace TypeScript version in VS Code. Run the "TypeScript: Select TypeScript Version" command and choose "Use Workspace Version".

🎁 Other Improvements

• Component declarationPath – You can now specify a custom declaration path for components (#​33419)
• Module resolution extensions – Kit's resolveModule now accepts an extensions option (#​33328)
• Global head utility – New setGlobalHead utility in kit for easier head management (#​33512)

🩹 Important Fixes

• Route hash is now preserved when redirecting based on routeRules (#​33222)
• Fixed concurrent calls to loadNuxtConfig with proper cleanup (#​33420)
• Object-format href now works correctly in <NuxtLink> (c69e4c30d)
• Component auto-imports now work as arguments to Vue's h() function (#​33509)
• Fixed app config array handling during HMR (#​33555)

✅ Upgrading

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

• nuxt: Allow specifying component declarationPath (#​33419)
• kit: Add extensions option for resolveModule (#​33328)
• nuxt: Add abortController option to useAsyncData (#​32531)
• nuxt: Display youch error page w/ user error page in dev (#​33359)
• nuxt: Experimental typescript plugin support (#​33314)
• nuxt,schema: Extract asyncData handlers to chunks (#​33131)
• schema: Enable setting future.compatibilityVersion to 5 (22f4693a1)
• kit,vite: Allow enabling vite environment api (#​33492)
• kit: Add setGlobalHead utility (#​33512)

🔥 Performance

• nuxt: Precompute renderer dependencies at build time (#​33361)
• kit,schema: Remove some unnecessary dependencies (7ae2cf563)

🩹 Fixes

• nuxt: Preserve hash with redirecting based on routeRules (#​33222)
• kit: Safely cleanup loadNuxtConfig in concurrent calls (#​33420)
• nuxt: Allow object-format href in <NuxtLink> (c69e4c30d)
• nuxt: Remove mergeModels from auto imports (#​33344)
• nuxt: Add back shortPath property (#​33384)
• nuxt: Do not allow native attrs to shadow nuxt link props (4751a6aca)
• nuxt: Remove declarationPath from component dirs (191bcb7e9)
• nuxt: Preserve root route in isPrerendered check (#​33476)
• nuxt: Exempt webpack vfs from pkg lookup (285eac31c)
• nitro: Exempt nightly release from import protections (dd522394a)
• webpack,rspack: Preserve prerender + nitro flags in server builds (#​33503)
• nuxt: Support component auto-imports as arguments of h() (#​33509)
• vite: Prevent assignment for rolldown's replacement plugin (#​33526)
• nuxt: Use sha256 hash for prerender cache keys (#​33505)
• nuxt: Add NuxtTime relative time numeric prop (#​33552)
• nuxt: Add NuxtTime relative time relativeStyle prop (#​33557)
• nuxt: Handle arrays in app config correctly during HMR (#​33555)
• vite: Unset optimizeDeps.include for server environment (#​33550)

💅 Refactors

• Remove obsolete shortPath property (#​33384)
• kit: Extract trace utilities (9687505ac)
• nuxt,vite,webpack: Allow builders to augment types (#​33427)
• schema: Deprecate extend, extendConfig, and configResolved hooks (e060b9695)
• vite: Make vite plugins environment-compatible (#​33445)
• nitro,nuxt: Extract @nuxt/nitro-server package (#​33462)
• nuxt: Use RouteLocationNormalizedLoadedGeneric internally (b51cb3067)

📖 Documentation

• Update link to localisation issue (d32859da2)
• Add nuxt module addServerPlugin note (#​33409)
• Remove deprecated node version (#​33411)
• Update declarationPath in addComponent (#​33380)
• Reproduction links for Nuxt v4 (#​33429)
• Add some notes/deprecations for vite hooks (31c5f26a2)
• Fix incorrect ESM module field info (#​33451)
• Recommend getLayerDirectories() instead of nuxt.options._layers (#​33484)
• Add 4.x prefix (5c0bb9285)
• Add docs for moduleDependencies (#​33499)
• Clarify extends removal in TypeScript config migration (#​33523)
• Pin codemod to v0.18.7 for migration recipe (#​33522)
• Fix links (#​33554)

🏡 Chore

• Migrate gitpod to ona (#​33159)
• Use native node to run test:prepare (6ef632b82)
• Do not use native node to run test:prepare (eca36cfe5)
• Lint docs (3b9784111)
• Update valid semantic scopes (3c38d1f8b)
• Ignore nitro templates (27cf85bdc)
• Update internal links (aac763017)
• Remove vue-demi from ignoredBuiltDependencies (#​33494)
• Update vscode url (#​33360)
• Correct jsdoc location for function used as parameters (#​33507)
• Remove code comment (#​33515)
• Patch changelogen for large numbers of commits (bd36738b8)
• Link Nuxt 1.x and 2.x (2016–2022) history to main (85838dfd9)
• Filter out commits before last tag when constructing changelog (1c561daeb)
• Also respect since date for bump type (08900f610)
• Also respect since in nightly releases (74ca73ca1)
• Ignore @rollup/plugin-commonjs (cd12980ce)

✅ Tests

• Refactor suite to use common matrix utils (#​33483)

🤖 CI

• Publish @nuxt/nitro-server on pkg-pr-new (b7ccf17bf)
• Remove nitro-server publish until v4.2 is released (904d4f6ec)

❤️ Contributors

• 山吹色御守 (@​KazariEX)
• Florian Heuberger (@​Flo0806)
• Daniel Roe (@​danielroe)
• Matej Černý (@​cernymatej)
• Trung Dang (@​NamesMT)
• 纸鹿/Zhilu (@​L33Z22L11)
• Julien Huang (@​huang-julien)
• Alexander Lichter (@​TheAlexLichter)
• abeer0 (@​iiio2)
• Max (@​onmax)
• Daniel Slepov (@​imslepov)
• Octavio Araiza (@​8ctavio)
• Bobbie Goede (@​BobbieGoede)
• DipakHalkude (@​DipakHalkude)
• Aleksander Błaszkiewicz (@​ablaszkiewicz)

v4.1.3

Compare Source

4.1.3 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

• vite: Use rolldown's replace plugin when applicable (#​33258)

🩹 Fixes

• kit: Add default values when adding type references in prepare:types hook (#​33239)
• nuxt: Augment app config in server context (#​33287)
• nuxt: Make lazy component types compatible with h (#​33046)
• vite: Deduplicate inlined server style chunks (#​33308)
• nuxt: Support head option on useHead (#​33318)
• nuxt: Do not relativise importmap if cdnURL is set (#​33333)
• nuxt: Resolve aliases in imports.dirs (#​33334)
• nuxt: Add missing element/vnode props for <NuxtLink> (#​33335)
• nuxt: Do not generate server placeholder components (#​33345)
• nuxt: Dedupe generated component names (#​33346)
• webpack: Test watch instance before closing it (0e5a0a5a0)
• nuxt: Correctly handle island rendering error (#​33302)
• nuxt: Support v-slot:fallback longform syntax in <DevOnly> (#​33368)
• nuxt: Support typeFrom when generating auto-import type templates (#​33373)
• nuxt: Don't trigger scroll when changing trailing slash (#​33358)
• nuxt: Add stubs for new scripts from @nuxt/scripts (bed410d60)
• nuxt: Prevent duplicate execution on key change in useAsyncData (#​33325)
• nuxt: Make middleware _path property configurable for HMR (#​33379)
• nuxt: Handle non-immediate useAsyncData with different key on ssr (#​33341)

💅 Refactors

• nuxt: Improve implementation of error composables (#​33234)
• nuxt: Resolve path of typed-router.d.ts early for consistency (#​33285)
• nuxt: Move server references to nitro:prepare:types hook (#​33286)
• nuxt: Place filename into componentsIslandsTemplate definition (#​33394)
• nuxt,vite: Use environment-api compatible plugins (#​33403)

📖 Documentation

• Add 4.x prefix to all internal links (#​33264)
• Fix more links (#​33265)
• Update usage instructions for Windows users (#​33284)
• Update app config paths to use app/app.config.ts (#​33297)
• Remove d suffix in example (#​33298)
• Move directory structure to top-level (#​33299)
• Add information about useFetch reactivity (#​33317)
• Add more 4.x prefixes in urls (47ea684c7)
• Lint code samples within docs (#​33271)
• Remove duplicated documentation from nuxt.config page (b438d44e1)
• Remove docs for outdated asyncData configuration (3e4a999e6)
• Note prepare command NODE_ENV behavior (#​33330)
• Update nuxt command pages (#​33336)

🏡 Chore

• Temporarily disable link to github sponsors (7e5375390)
• Update markdownlint ignore (19fc9abbb)
• Migrate pnpm settings out of .npmrc (14514329b)
• Ignore errors from npmjs (50febbbba)
• Lint (09a16d9df)
• nuxt: Align global components indent (#​33340)
• Remove tea.yaml (5f567c79b)
• Remove todo comment as resolved (#​33389)

✅ Tests

• nuxt: Set locale to en for nuxt-time tests (#​33343)
• Double gotoPath timeout in CI (f1e5a2d4c)

🤖 CI

• Add provenance action to check for downgrades in provenance (5ada6861e)
• Pass commit sha when triggering ecosystem ci (399df6bab)

❤️ Contributors

• Daniel Roe (@​danielroe)
• 山吹色御守 (@​KazariEX)
• Julien Huang (@​huang-julien)
• Florian Heuberger (@​Flo0806)
• Ondrej Brendy (@​bandiasek)
• Octavio Araiza (@​8ctavio)
• Alex Liu (@​Mini-ghost)
• Bobbie Goede (@​BobbieGoede)
• abeer0 (@​iiio2)
• Harlan Wilton (@​harlan-zw)
• Alexander Lichter (@​TheAlexLichter)
• Sébastien Chopin (@​atinux)
• Ben Hong (@​bencodezen)
• Daniel Slepov (@​imslepov)
• Huseyn Guliyev (@​husayt)
• Hillary (@​hillaryke)

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 inter

---

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 is behind base branch, 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 88.67%. Comparing base (0965a13) to head (367173e).

❗ Current head 367173e differs from pull request most recent head 9e24fa9

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #605   +/-   ##
=======================================
  Coverage   88.67%   88.67%           
=======================================
  Files           1        1           
  Lines          53       53           
  Branches       29       29           
=======================================
  Hits           47       47           
  Misses          6        6           

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