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.

Screenshot of the new development error page

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)