v4.3.1

4.3.1 is a regularly scheduled patch release.

👉 Changelog

compare changes

🩹 Fixes

• nuxt: Correct reference format of server builder (#34177)
• nuxt: Add status/statusText getters to NuxtError (#34188)
• nuxt: Don't inject shared types for differing auto-imports (#34191)
• schema: Add direnv and vendor to default ignore (#34190)
• nuxt: Focus hash links after navigation (#34193)
• nuxt: Exclude head runtime from unhead imports transform (#34195)
• kit: Include prereleases in semver satisfy check (#34210)
• nitro: Encode unicode paths in x-nitro-prerender header (#34202)
• nuxt: Watch server/ for builder:watch hook (#34208)
• nitro: Preserve error.message for fatal errors (#34226)
• Only enable dynamic imports when ts plugin (#34205)
• webpack: Use H3Error for 403 in dev server (#34233)
• nuxt: Ensure NuxtError extends Error type (#34242)
• vite: Use H3Error for 404 in dev server (#34225)
• nuxt: Add backwards compat for #app barrel export in keyed functions (#34199)
• nuxt: Track + re-add custom routes on hmr (#32044)
• nuxt: Keep vnode when leaving deeper nested route (#33778)
• vite: Prevent CSS flickering in dev mode after config changes (#33856)
• nuxt: Do not start view transition if there is no route (#33723)
• nuxt: Call deferHydration done on NuxtPage unmount (#34152)
• nuxt: Handle invalid datetime in ` (#33992)
• nuxt: Preserve middleware error status in 404 fallback (#34148)
• nitro: Do not augment nuxt/schema (#34255)
• nuxt: Cache manifest files to preserve buildId (#34002)
• nuxt: Don't decode query string in SSR context URL (#34252)
• nuxt: Allow specifying moduleDependencies by meta.name (#34263)
• nuxt: Resolve #components import mapping conflict for packages outside rootDir (#34139)
• vite,webpack: Use node.res to send 403/404 (#34266)
• nitro,nuxt: Align path encoding with vue-router (#34265)
• nitro: Augment nuxt/schema once more (552bbd8d1)

💅 Refactors

• nuxt: Prefer genObjectKey to omit unnecessary quotes (#34245)
• nuxt: Use ComponentProps helper to extract layout props (#34248)

📖 Documentation

• Update roadmap dates (#34166)
• Correct default value of nitroAutoImports (#34182)
• Clarify shared type context limitations for custom imports (#34194)
• Fix broken links (#34223)
• Document payload extraction for ISR/SWR routes (#34222)
• Update default aliases in configuration reference (#34237)
• Update example of email validation (#34247)
• Align server alias examples with #server and rootDir (#34259)
• Add documentation for keyedComposables (#34201)

🏡 Chore

• Remove px from width attribute (8d1cbb27a)
• Add ai config in gitignore (#34220)

✅ Tests

• Vitest v4 compatibility (825b2c202)
• Add runtime tests for deeply nested <NuxtPage> navigation (048efc030)

❤️ Contributors

• Daniel Roe (@danielroe)
• Matej Černý (@cernymatej)
• Octavio Araiza (@8ctavio)
• Muhammad Yasir Ghaffar (@M-YasirGhaffar)
• mrkaashee (@mrkaashee)
• Max (@onmax)
• Bobbie Goede (@BobbieGoede)
• 纸鹿/Zhilu (@L33Z22L11)
• Florian Heuberger (@Flo0806)
• 山吹色御守 (@KazariEX)
• ExXTreMe315 (@ExXTreMe315)
• Eugene (@FlexIDK)
• abeer0 (@iiio2)
• Jonas Thelemann (@dargmuesli)
• Erwan Jugand (@erwanjugand)

v3.21.1

3.21.1 is a regularly schedule patch release.

👉 Changelog

compare changes

🩹 Fixes

• nuxt: Correct reference format of server builder (#34177)
• nuxt: Add status/statusText getters to NuxtError (#34188)
• schema: Add direnv and vendor to default ignore (#34190)
• nuxt: Focus hash links after navigation (#34193)
• nuxt: Exclude head runtime from unhead imports transform (#34195)
• kit: Include prereleases in semver satisfy check (#34210)
• nuxt: Watch server/ for builder:watch hook (#34208)
• nitro: Encode unicode paths in x-nitro-prerender header (#34202)
• nitro: Preserve error.message for fatal errors (#34226)
• Only enable dynamic imports when ts plugin (#34205)
• webpack: Use H3Error for 403 in dev server (#34233)
• nuxt: Ensure NuxtError extends Error type (#34242)
• vite: Use H3Error for 404 in dev server (#34225)
• nuxt: Add backwards compat for #app barrel export in keyed functions (#34199)
• nuxt: Track + re-add custom routes on hmr (#32044)
• nuxt: Keep vnode when leaving deeper nested route (#33778)
• vite: Prevent CSS flickering in dev mode after config changes (#33856)
• nuxt: Do not start view transition if there is no route (#33723)
• nuxt: Call deferHydration done on NuxtPage unmount (#34152)
• nuxt: Handle invalid datetime in ` (#33992)
• nuxt: Preserve middleware error status in 404 fallback (#34148)
• nitro: Do not augment nuxt/schema (#34255)
• nuxt: Cache manifest files to preserve buildId (#34002)
• nuxt: Don't decode query string in SSR context URL (#34252)
• nuxt: Allow specifying moduleDependencies by meta.name (#34263)
• nuxt: Resolve #components import mapping conflict for packages outside rootDir (#34139)
• vite,webpack: Use node.res to send 403/404 (#34266)
• nitro,nuxt: Align path encoding with vue-router (#34265)
• nitro: Augment nuxt/schema once more (9f5bb611d)

💅 Refactors

• nuxt: Prefer genObjectKey to omit unnecessary quotes (#34245)
• nuxt: Use ComponentProps helper to extract layout props (#34248)

📖 Documentation

• Remove link to ai guide entirely (084b5d7f2)
• Update roadmap dates (#34166)
• Clarify shared type context limitations for custom imports (#34194)
• Fix broken links (#34223)
• Document payload extraction for ISR/SWR routes (#34222)
• Update example of email validation (#34247)
• Add documentation for keyedComposables (#34201)

🏡 Chore

• Remove px from width attribute (e80147f7d)
• Add ai config in gitignore (#34220)

✅ Tests

• Vitest v4 compatibility (70e147b71)
• Add runtime tests for deeply nested <NuxtPage> navigation (707a9dc44)
• Resolve merge issues in tests (85abddc54)

❤️ Contributors

• Daniel Roe (@danielroe)
• Matej Černý (@cernymatej)
• Octavio Araiza (@8ctavio)
• Muhammad Yasir Ghaffar (@M-YasirGhaffar)
• Max (@onmax)
• Bobbie Goede (@BobbieGoede)
• 纸鹿/Zhilu (@L33Z22L11)
• Florian Heuberger (@Flo0806)
• 山吹色御守 (@KazariEX)
• ExXTreMe315 (@ExXTreMe315)
• Eugene (@FlexIDK)
• abeer0 (@iiio2)
• Jonas Thelemann (@dargmuesli)
• Erwan Jugand (@erwanjugand)

v4.3.0

4.3.0 is the next minor release.

Nuxt 4.3 brings powerful new features for layouts, caching, and developer experience – plus significant performance improvements under the hood.

📣 Some News

Extended v3 Support

Early this month, I opened a discussion to find out how the upgrade had gone from v3 to v4. I was really pleased to hear how well it had gone for most people.

Having said that, we're committed to making sure no one gets left behind. And so we will continue to provide security updates and critical bug fix releases beyond the previously announced end-of-life date of January 31, 2026, meaning Nuxt v3 will meet its end-of-life on July 31, 2026.

Tip

As usual, today also brings a minor release for v3, with many of the same improvements backported from v4.3.

Preparing for Nuxt 5

We're closer than ever to the releases of Nuxt v5 and Nitro v3. In the coming weeks, the main branch of the Nuxt repository will begin receiving initial commits for Nuxt 5. However, it's still business as usual.

• Continue making pull requests to the main branch
• We'll backport changes to the 4.x and 3.x branches

Keep an eye out on the Upgrade Guide – we'll be adding details about how you can already start migrating your projects to prepare for Nuxt v4 with future.compatibilityVersion: 5.

🗂️ Route Rule Layouts

But that's enough about the future. We have a lot of good things for you today!

First, you can now set layouts directly in route rules using the new appLayout property (#31092). This provides a centralized, declarative way to manage layouts across your application without scattering definePageMeta calls throughout your pages.

export default defineNuxtConfig({
  routeRules: {
    '/admin/**': { appLayout: 'admin' },
    '/dashboard/**': { appLayout: 'dashboard' },
    '/auth/**': { appLayout: 'minimal' }
  }
})

This might be useful for:

• Admin panels with a shared layout across many routes
• Marketing pages that need a different layout from the app

Tip

Plus, you can pass props to layouts now! See the setPageLayout improvements below.

📦 ISR/SWR Payload Extraction

Payload extraction now works with ISR (incremental static regeneration), SWR (stale-while-revalidate) and cache routeRules (#33467). Previously, only pre-rendered pages could generate _payload.json files.

This means:

• Client-side navigation to ISR/SWR pages can use cached payloads
• CDNs (Vercel, Netlify, Cloudflare) can cache payload files alongside HTML
• Fewer API calls during navigation – data can be prefetched and served from the cached payload

export default defineNuxtConfig({
  routeRules: {
    '/products/**': { 
      isr: 3600, // Revalidate every hour
    }
  }
})

🧹 Dev Mode Payload Extraction

Related to the above, payload extraction now also works in development mode (#30784). This makes it easier to test and debug payload behavior without needing to run a production build.

Important

Payload extraction works in dev mode with nitro.static set to true, or for individual pages which have isr, swr, prerender or cache route rules.

🚫 Disable Modules from Layers

When extending Nuxt layers, you can now disable specific modules that you don't need (#33883). Just pass false to the module's options:

export default defineNuxtConfig({
  extends: ['../shared-layer'],
  // disable @nuxt/image from layer
  image: false,
})

🏷️ Route Groups in Page Meta

Route groups (folders wrapped in parentheses like (protected)/) are now exposed in page meta (#33460). This makes it easy to check which groups a route belongs to in middleware or anywhere you have access to the route.

<script setup lang="ts">
// This page's meta will include: { groups: ['protected'] }
useRoute().meta.groups
</script>

export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.groups?.includes('protected') && !isAuthenticated()) {
    return navigateTo('/login')
  }
})

This provides a clean, convention-based approach to route-level authorization without needing to add definePageMeta to every protected page.

🎨 Layout Props with setPageLayout

The setPageLayout composable now accepts a second parameter to pass props to your layout (#33805):

export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    theme: 'dark'
  })
})

<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  theme?: 'light' | 'dark'
}>()
</script>

🔧 #server Alias

A new #server alias provides clean imports within your server directory (#33870), similar to how #shared works:

// Before: relative path hell
import { helper } from '../../../../utils/helper'

// After: clean and predictable
import { helper } from '#server/utils/helper'

The alias includes import protection – you can't accidentally import #server code from client or shared contexts.

🪟 Draggable Error Overlay

The development error overlay introduced in Nuxt 4.2 is now draggable and can be minimized (#33695). You can:

• Drag it to any corner of the screen (it snaps to edges)
• Minimize it to a small pill button when you want to keep working
• Your position and minimized state persist across page reloads

This is a quality-of-life improvement when you're iterating on fixes and don't want the overlay blocking your view.

https://github.com/user-attachments/assets/nuxt_4-3_error_demo.mp4

⚙️ Async Plugin Constructors

Module authors can now use async functions when adding build plugins (#33619):

export default defineNuxtModule({
  async setup() {
    // Lazy load only when actually needed
    addVitePlugin(() => import('my-cool-plugin').then(r => r.default()))
    
    // No need to load webpack plugin if using Vite
    addWebpackPlugin(() => import('my-cool-plugin/webpack').then(r => r.default()))
  }
})

This enables true lazy loading of build plugins, avoiding unnecessary code loading when plugins aren't needed.

🚀 Performance Improvements

This release includes several performance optimizations for faster builds:

• Hook filters - Internal plugins now use filters to avoid running hooks unnecessarily (#33898)
• SSR styles optimization - The nuxt:ssr-styles plugin is now significantly faster (#33862, #33865)
• Layer alias transform - Skipped when using Vite (it handles this natively) (#33864)
• Route rules compilation - Route rules are now compiled into a client chunk using rou3, removing the need for radix3 in the client bundle and eliminating app manifest fetches (#33920)

🎨 Inline Styles for Webpack/Rspack

The inlineStyles feature now works with webpack and rspack builders (#33966), not just Vite. This enables critical CSS inlining for better Core Web Vitals regardless of your bundler choice.

⚠️ Deprecations

statusCode → status, statusMessage → statusText

In preparation for Nitro v3 and H3 v2, we're moving to use Web API naming conventions (#33912). The old properties still work but are deprecated in advance of v5:

- throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+ throw createError({ status: 404, statusText: 'Not Found' })

🐛 Bug Fixes

Notable fixes in this release:

• Fixed head component deduplication using key attribute (#33958, #33963)
• Fixed async data properties not being reactive in Options API (#34119)
• Fixed useCookie unsafe number parsing during decode (#34007)
• Fixed NuxtPage not re-rendering when nested NuxtLayout has layouts disabled (#34078)
• Fixed client-side pathname decoding for non-ASCII route aliases (#34043)
• Fixed suspense remounting when navigating after pending state (#33991)
• Fixed clipboard copy in error overlay (#33873)
• Enabled allowArbitraryExtensions by default in TypeScript config (#34084)
• Added noUncheckedIndexedAccess to server tsconfig for safer typing (#33985)

Important

Enabling noUncheckedIndexedAccess in the Nitro server TypeScript config improves type safety but may surface new type errors in your server code. This change was necessary because Nuxt's app context performs type checks on server rou...

v3.21.0

3.21.0 is the next minor release.

Nuxt 4.3 and 3.21 bring powerful new features for layouts, caching, and developer experience – plus significant performance improvements under the hood.

📣 Some News

Extended v3 Support

Early this month, I opened a discussion to find out how the upgrade had gone from v3 to v4. I was really pleased to hear how well it had gone for most people.

Having said that, we're committed to making sure no one gets left behind. And so we will continue to provide security updates and critical bug fix releases beyond the previously announced end-of-life date of January 31, 2026, meaning Nuxt v3 will meet its end-of-life on July 31, 2026.

Tip

As usual, today also brings a minor release for v3, with many of the same improvements backported from v4.3.

Preparing for Nuxt 5

We're closer than ever to the releases of Nuxt v5 and Nitro v3. In the coming weeks, the main branch of the Nuxt repository will begin receiving initial commits for Nuxt 5. However, it's still business as usual.

• Continue making pull requests to the main branch
• We'll backport changes to the 4.x and 3.x branches

Keep an eye out on the Upgrade Guide – we'll be adding details about how you can already start migrating your projects to prepare for Nuxt v4 with future.compatibilityVersion: 5.

🗂️ Route Rule Layouts

But that's enough about the future. We have a lot of good things for you today!

First, you can now set layouts directly in route rules using the new appLayout property (#31092). This provides a centralized, declarative way to manage layouts across your application without scattering definePageMeta calls throughout your pages.

export default defineNuxtConfig({
  routeRules: {
    '/admin/**': { appLayout: 'admin' },
    '/dashboard/**': { appLayout: 'dashboard' },
    '/auth/**': { appLayout: 'minimal' }
  }
})

This might be useful for:

• Admin panels with a shared layout across many routes
• Marketing pages that need a different layout from the app

Tip

Plus, you can pass props to layouts now! See the setPageLayout improvements below.

📦 ISR/SWR Payload Extraction

Payload extraction now works with ISR (incremental static regeneration), SWR (stale-while-revalidate) and cache routeRules (#33467). Previously, only pre-rendered pages could generate _payload.json files.

This means:

• Client-side navigation to ISR/SWR pages can use cached payloads
• CDNs (Vercel, Netlify, Cloudflare) can cache payload files alongside HTML
• Fewer API calls during navigation – data can be prefetched and served from the cached payload

export default defineNuxtConfig({
  routeRules: {
    '/products/**': { 
      isr: 3600, // Revalidate every hour
    }
  }
})

🧹 Dev Mode Payload Extraction

Related to the above, payload extraction now also works in development mode (#30784). This makes it easier to test and debug payload behavior without needing to run a production build.

Important

Payload extraction works in dev mode with nitro.static set to true, or for individual pages which have isr, swr, prerender or cache route rules.

🚫 Disable Modules from Layers

When extending Nuxt layers, you can now disable specific modules that you don't need (#33883). Just pass false to the module's options:

export default defineNuxtConfig({
  extends: ['../shared-layer'],
  // disable @nuxt/image from layer
  image: false,
})

🏷️ Route Groups in Page Meta

Route groups (folders wrapped in parentheses like (protected)/) are now exposed in page meta (#33460). This makes it easy to check which groups a route belongs to in middleware or anywhere you have access to the route.

<script setup lang="ts">
// This page's meta will include: { groups: ['protected'] }
useRoute().meta.groups
</script>

export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.groups?.includes('protected') && !isAuthenticated()) {
    return navigateTo('/login')
  }
})

This provides a clean, convention-based approach to route-level authorization without needing to add definePageMeta to every protected page.

🎨 Layout Props with setPageLayout

The setPageLayout composable now accepts a second parameter to pass props to your layout (#33805):

export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    theme: 'dark'
  })
})

<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  theme?: 'light' | 'dark'
}>()
</script>

🔧 #server Alias

A new #server alias provides clean imports within your server directory (#33870), similar to how #shared works:

// Before: relative path hell
import { helper } from '../../../../utils/helper'

// After: clean and predictable
import { helper } from '#server/utils/helper'

The alias includes import protection – you can't accidentally import #server code from client or shared contexts.

🪟 Draggable Error Overlay

The development error overlay introduced in Nuxt 4.2 is now draggable and can be minimized (#33695). You can:

• Drag it to any corner of the screen (it snaps to edges)
• Minimize it to a small pill button when you want to keep working
• Your position and minimized state persist across page reloads

This is a quality-of-life improvement when you're iterating on fixes and don't want the overlay blocking your view.

https://github.com/user-attachments/assets/nuxt_4-3_error_demo.mp4

⚙️ Async Plugin Constructors

Module authors can now use async functions when adding build plugins (#33619):

export default defineNuxtModule({
  async setup() {
    // Lazy load only when actually needed
    addVitePlugin(() => import('my-cool-plugin').then(r => r.default()))
    
    // No need to load webpack plugin if using Vite
    addWebpackPlugin(() => import('my-cool-plugin/webpack').then(r => r.default()))
  }
})

This enables true lazy loading of build plugins, avoiding unnecessary code loading when plugins aren't needed.

🚀 Performance Improvements

This release includes several performance optimizations for faster builds:

• Hook filters - Internal plugins now use filters to avoid running hooks unnecessarily (#33898)
• SSR styles optimization - The nuxt:ssr-styles plugin is now significantly faster (#33862, #33865)
• Layer alias transform - Skipped when using Vite (it handles this natively) (#33864)
• Route rules compilation - Route rules are now compiled into a client chunk using rou3, removing the need for radix3 in the client bundle and eliminating app manifest fetches (#33920)

🎨 Inline Styles for Webpack/Rspack

The inlineStyles feature now works with webpack and rspack builders (#33966), not just Vite. This enables critical CSS inlining for better Core Web Vitals regardless of your bundler choice.

⚠️ Deprecations

statusCode → status, statusMessage → statusText

In preparation for Nitro v3 and H3 v2, we're moving to use Web API naming conventions (#33912). The old properties still work but are deprecated in advance of v5:

- throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+ throw createError({ status: 404, statusText: 'Not Found' })

🐛 Bug Fixes

Notable fixes in this release:

• Fixed head component deduplication using key attribute (#33958, #33963)
• Fixed async data properties not being reactive in Options API (#34119)
• Fixed useCookie unsafe number parsing during decode (#34007)
• Fixed NuxtPage not re-rendering when nested NuxtLayout has layouts disabled (#34078)
• Fixed client-side pathname decoding for non-ASCII route aliases (#34043)
• Fixed suspense remounting when navigating after pending state (#33991)
• Fixed clipboard copy in error overlay (#33873)
• Enabled allowArbitraryExtensions by default in TypeScript config (#34084)
• Added noUncheckedIndexedAccess to server tsconfig for safer typing (#33985)

Important

Enabling noUncheckedIndexedAccess in the Nitro server TypeScript config improves type safety but may surface new type errors in your server code. This change was necessary because Nuxt's app context performs type checks on s...

v4.2.2

4.2.2 is the next 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

• nitro: Do not show pretty error handler when testing (243261edb)
• nuxt: Generate valid references for component declaration items (#33388)
• nuxt: Sync internal route before calling page:finish hook (#33707)
• kit: Add TypeScript path alias support for test files (#33672)
• nitro: Ensure html is a string before injecting error handler (f70b70c97)
• nitro: Include layer server directories in tsconfig.server.json (#33510)
• nuxt: Ensure deduped async data executions return latest promise (#33740)
• kit,nuxt: Type + respect moduleDependencies by meta name (#33774)
• nuxt,schema: Ignore .d.vue.ts declarations (1c73525a2)
• kit,nuxt: Protect against resolved nuxt module subpath (#33767)
• nuxt: Re-execute callOnce during HMR (#33810)
• nuxt: Resolve watch callback after reactive key change in useAsyncData (#33802)
• nuxt: Escape HTML in development error page stack trace (#33820)
• kit: Do not add resolved rootDir to cached layer config (#33779)
• kit,schema: Add moduleDependencies -> installModule (#33689)

💅 Refactors

• nuxt: Improve type safety within callOnce function (#33825)

📖 Documentation

• Split directory structure and re-order guides (v4) (#33691)
• Add hints release (#33701)
• Fix link to vitest globals config (#33702)
• Add mcp server and llms.txt (#33371)
• Fix 404 link (98c2f1397)
• Text consistency (#33709)
• Type error as non-optional prop (#33763)
• Reformat tables (#33813)

🏡 Chore

• Update pnpm to 10.21 and enable trust policy (d2c9711c0)
• Revert pnpm trust policy and restore provenance action (f9d0e0a3d)
• Update markdownlint config to ignore mdc issues (e7fff7132)
• Pin to single version of unstorage (ec316eae8)

✅ Tests

• Add patchProp and nodeOps to excluded Vue helpers (#33754)
• Use fake timers for watch params test (08d9d2f3b)

🤖 CI

• Add --pnpm flag to correctly publish prerelease (#33688)
• Update action lint config (#33710)

❤️ Contributors

• Daniel Roe (@danielroe)
• Florian Heuberger (@Flo0806)
• Konstantin Telyakov (@kTelyakov)
• abeer0 (@iiio2)
• Julien Huang (@huang-julien)
• Matej Černý (@cernymatej)
• Robin (@OrbisK)
• Dheeraj Joshi (@dheeraj3587)
• Alexander Lichter (@TheAlexLichter)
• Edwin Samodra (@edwinsamodra)
• edison (@edison1105)
• 山吹色御守 (@KazariEX)
• Sébastien Chopin (@atinux)
• Hugo (@HugoRCD)
• pierreoa (@pierreoa)
• Maxime Pauvert (@maximepvrt)

v3.20.2

3.20.2 is the next patch release.

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxt upgrade --dedupe --channel=v3

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.

Note

This will only work if you already have a version of @nuxt/cli which has the --channel flag. If this does not work, you can instead run npx nuxi@latest for the initial upgrade.

👉 Changelog

compare changes

🩹 Fixes

• nitro: Do not show pretty error handler when testing (cc75ce409)
• nuxt: Generate valid references for component declaration items (#33388)
• nuxt: Sync internal route before calling page:finish hook (#33707)
• nitro: Ensure html is a string before injecting error handler (6f51a25e9)
• nitro: Include layer server directories in tsconfig.server.json (#33510)
• nuxt: Ensure deduped async data executions return latest promise (#33740)
• kit,nuxt: Type + respect moduleDependencies by meta name (#33774)
• nuxt,schema: Ignore .d.vue.ts declarations (9a6a770ab)
• kit,nuxt: Protect against resolved nuxt module subpath (#33767)
• nuxt: Re-execute callOnce during HMR (#33810)
• nuxt: Resolve watch callback after reactive key change in useAsyncData (#33802)
• nuxt: Escape HTML in development error page stack trace (#33820)
• kit: Do not add resolved rootDir to cached layer config (#33779)
• kit,schema: Add moduleDependencies -> installModule (#33689)

💅 Refactors

• nuxt: Improve type safety within callOnce function (#33825)

📖 Documentation

• Split directory structure and re-order guides (v3) (#33690)
• Fix link (016ef66e3)
• Add hints release (#33701)
• Fix link to vitest globals config (#33702)
• Fix 404 link (5543b7cf7)
• Text consistency (#33709)
• Type error as non-optional prop (#33763)

🏡 Chore

• Update pnpm to 10.21 and enable trust policy (1cb55efc0)
• Revert pnpm trust policy and restore provenance action (103ae1351)
• Update markdownlint config to ignore mdc issues (d4933e26e)
• Pin to single version of unstorage (619956e7f)

✅ Tests

• Add patchProp and nodeOps to excluded Vue helpers (#33754)
• Use fake timers for watch params test (58607fbea)
• Update test for v3 defaults (daa002638)

🤖 CI

• Add --pnpm flag to correctly publish prerelease (#33688)
• Update action lint config (#33710)

❤️ Contributors

• Daniel Roe (@danielroe)
• Alexander Lichter (@TheAlexLichter)
• Florian Heuberger (@Flo0806)
• Konstantin Telyakov (@kTelyakov)
• abeer0 (@iiio2)
• Julien Huang (@huang-julien)
• Robin (@OrbisK)
• Dheeraj Joshi (@dheeraj3587)
• Edwin Samodra (@edwinsamodra)
• edison (@edison1105)
• 山吹色御守 (@KazariEX)
• Sébastien Chopin (@atinux)
• pierreoa (@pierreoa)
• Maxime Pauvert (@maximepvrt)

v4.2.1

4.2.1 is the next 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

• kit,nuxt,schema: Deprecate ImportPresetWithDeprecation (#33596)
• nuxt: Correct warning message for prefetch/noPrefetch conflict (#33617)
• nitro: Remove <nuxt-error-overlay> iframe border (#33625)
• vite: Use rolldown replace only in build (#33615)
• nitro: Use directory paths in moduleEntryPaths (#33628)
• nitro: Start error overlay minimized based on status code (#33658)
• vite: Ensure optimizeDeps config is applied before other plugins (#33586)
• nuxt: Respect layer priority order for scanned components (#33654)
• nuxt: Process prerender routes on pages:resolved (#33662)
• nuxt: Remove abort signal event listeners after render (#33665)
• nuxt: Cleanup event listener with cleanup signal (#33667)
• vite: Update vite-node (#33663)
• vite: Respect vite proxy in dev middleware (#33670)

💅 Refactors

• kit,nitro,nuxt,schema,vite: Explicitly import process/performance (#33650)

📖 Documentation

• Fix typo in eslint flat config description (#33569)
• Add signal support to useAsyncData examples (#33601)
• Document pending as alias of status === 'pending' (#33221)
• Note that cookieStore is true by default (#33572)
• Add information on types for server context (#33511)
• Mark webstorm issue resolved (#33608)
• Clarify route middleware doesn't affect API routes (#33643)
• Improve docs for useHead/useHydration/useLazy* (#33626)
• Update link to nitro source to v2 branch (08018af4f)
• Add typescript documentation for module authors (#33637)
• Typo (#33655)

🏡 Chore

• Update URLs (#33567)
• Add verifyDepsBeforeRun: install (#33603)
• Reduce redirects in docs links (1cc539325)
• Lint docs (0b5fa5dea)

🤖 CI

• Disable cache in release action (ff37598bc)

❤️ Contributors

• Daniel Roe (@danielroe)
• Anthony Fu (@antfu)
• Robin (@OrbisK)
• abeer0 (@iiio2)
• Bobbie Goede (@BobbieGoede)
• Florian Heuberger (@Flo0806)
• Matej Černý (@cernymatej)
• Peter Budai (@peterbud)
• Julien Huang (@huang-julien)
• Max (@onmax)
• 纸鹿/Zhilu (@L33Z22L11)
• Hinata Oishi (@te19oishi)
• Damian Głowala (@DamianGlowala)
• Maxime Pauvert (@maximepvrt)
• Raed Abdennadher (@RaedAbr)

v3.20.1

3.20.1 is the next patch release.

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxt upgrade --dedupe --channel=v3

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

• vite: Unset optimizeDeps.include for server environment (#33550)
• kit,nuxt,schema: Deprecate ImportPresetWithDeprecation (#33596)
• nuxt: Correct warning message for prefetch/noPrefetch conflict (#33617)
• nitro: Remove <nuxt-error-overlay> iframe border (#33625)
• vite: Use rolldown replace only in build (#33615)
• nitro: Use directory paths in moduleEntryPaths (#33628)
• nitro: Start error overlay minimized based on status code (#33658)
• vite: Ensure optimizeDeps config is applied before other plugins (#33586)
• nuxt: Respect layer priority order for scanned components (#33654)
• nuxt: Process prerender routes on pages:resolved (#33662)
• nuxt: Remove abort signal event listeners after render (#33665)
• nuxt: Cleanup event listener with cleanup signal (#33667)
• vite: Respect vite proxy in dev middleware (#33670)

💅 Refactors

• kit,nitro,nuxt,schema,vite: Explicitly import process/performance (#33650)

📖 Documentation

• Fix typo in eslint flat config description (#33569)
• Add signal support to useAsyncData examples (#33601)
• Note that cookieStore is true by default (#33572)
• Document pending as alias of status === 'pending' (#33221)
• Clarify route middleware doesn't affect API routes (#33643)
• Improve docs for useHead/useHydration/useLazy* (#33626)
• Typo (#33655)

🏡 Chore

• Add verifyDepsBeforeRun: install (#33603)
• Reduce redirects in docs links (bbdc72e35)
• Lint docs (352bdbc93)
• Remove verify deps before run (e9e1c5b97)

🤖 CI

• Disable cache in release action (885df65f4)

❤️ Contributors

• Daniel Roe (@danielroe)
• Robin (@OrbisK)
• abeer0 (@iiio2)
• Bobbie Goede (@BobbieGoede)
• Florian Heuberger (@Flo0806)
• Matej Černý (@cernymatej)
• Peter Budai (@peterbud)
• Julien Huang (@huang-julien)
• Max (@onmax)
• 纸鹿/Zhilu (@L33Z22L11)
• Hinata Oishi (@te19oishi)
• Damian Głowala (@DamianGlowala)
• Maxime Pauvert (@maximepvrt)
• Raed Abdennadher (@RaedAbr)

v3.20.0

3.20.0 is the next minor release.

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxt upgrade --dedupe --channel=v3

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

🚀 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)
• kit: Add setGlobalHead utility (#33512)
• kit,vite: Allow enabling vite environment api (#33492)

🔥 Performance

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

🩹 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> (b97ae2f70)
• nuxt: Remove mergeModels from auto imports (#33344)
• nuxt: Add back shortPath property (#33384)
• nuxt: Do not allow native attrs to shadow nuxt link props (0981990a7)
• nuxt: Remove declarationPath from component dirs (e384ba3cb)
• nuxt: Preserve root route in isPrerendered check (#33476)
• nuxt: Exempt webpack vfs from pkg lookup (4df1e8275)
• nitro: Exempt nightly release from import protections (272d9abbe)
• 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)

💅 Refactors

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

📖 Documentation

• Add nuxt module addServerPlugin note (#33409)
• Remove deprecated node version (#33411)
• Update declarationPath in addComponent (#33380)
• Add some notes/deprecations for vite hooks (2c6912d2f)
• Fix incorrect ESM module field info (#33451)
• Recommend getLayerDirectories() instead of nuxt.options._layers (#33484)
• Add docs for moduleDependencies (#33499)
• Pin codemod to v0.18.7 for migration recipe (#33522)

🏡 Chore

• Migrate gitpod to ona (#33159)
• Use native node to run test:prepare (cbad63c02)
• Do not use native node to run test:prepare (672c09423)
• Update valid semantic scopes (4ca29168b)
• Ignore nitro templates (ec59aceeb)
• 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 (b6530b5b6)
• Filter out commits before last tag when constructing changelog (257049712)
• Ignore @rollup/plugin-commonjs (c2bd323b8)
• Pin @rollup/plugin-commonjs (a524522ea)

✅ Tests

• Update runtime test to use asyncDataDefaults.errorValue (b6f1c9b0d)
• Refactor suite to use common matrix utils (#33483)
• Update typed router test (c55db2854)

🤖 CI

• Publish @nuxt/nitro-server on pkg-pr-new (d37ef17b0)
• Remove nitro-server publish until v4.2 is released (e34c2f52f)
• For now, use tag push to trigger release (0705b835f)

❤️ Contributors

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

v4.2.0

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 use AbortController signals directly within useAsyncData, giving you fine-grained control over request cancellation (#32531).

This works by passing an internal signal to your useAsyncData handler to cancel any promise that can be canceled, such as $fetch.

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

const { data, error, clear, refresh } = await useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', {
  signal
}))

refresh() // will actually cancel the $fetch request (if dedupe: cancel)
refresh() // will actually cancel the $fetch request (if dedupe: cancel)
refresh()
  
clear() // will cancel the latest pending handler
</script>

You also pass an AbortController signal directly to refresh/execute, giving you fine-grained control over request cancellation. This is particularly useful when you need to abort requests based on user actions or component lifecycle events.

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)
• **nu...