4.4.0/4.4.2 is the next minor release (v4.4.2 was published with no changes due to a publishing failure)

👀 Highlights

🏭 createUseFetch and createUseAsyncData

You can now create custom instances of useFetch and useAsyncData with your own default options (#32300).

// composables/api.ts

// Simple defaults
export const useClientFetch = createUseFetch({
  server: false,
})

// Dynamic defaults with full control over merging
export const useApiFetch = createUseFetch((currentOptions) => {
  const runtimeConfig = useRuntimeConfig()

  return {
    ...currentOptions,
    baseURL: currentOptions.baseURL ?? runtimeConfig.public.baseApiUrl,
  }
})

Then use them exactly like useFetch – they're fully typed and support all the same options:

<!-- pages/dashboard.vue -->
<script setup lang="ts">
// Uses your baseURL from runtimeConfig automatically
const { data: users } = await useApiFetch('/users')
</script>

When you pass a plain object, your usage options automatically override the defaults. When you pass a function, you get full control over how options are merged – which means you can compose interceptors, headers, and other complex options however you need.

Under the hood, this is powered by a new Nuxt ad-hoc module that scans your composables directory and automatically registers your custom instances for key injection – so they work seamlessly with SSR, just like useAsyncData and useFetch.

There's also createUseAsyncData for the same pattern with useAsyncData.

📖 Read more: createUseAsyncData

🗺️ Vue Router v5

We've upgraded to vue-router v5 (#34181), which removes the dependency on unplugin-vue-router. This is the first major vue-router upgrade since Nuxt 3, and it comes with a bunch of improvements under the hood.

For most apps, this should be a transparent upgrade. If you're using unplugin-vue-router directly, you can remove it from your dependencies.

The next step will be taking typed routes out of experimental status. 👀

💪 Typed Layout Props in definePageMeta

You can now pass props to your layouts directly from definePageMeta (#34262). This means your layouts can be parameterised per-page without needing to use provide/inject or other workarounds. Check out the updated docs for the full details.

// pages/dashboard.vue
definePageMeta({
  layout: {
    name: 'panel',
    props: {
      sidebar: true,
      title: 'Dashboard',
    },
  },
})

Even better – the props are fully typed (#34409). If your layout defines props, you'll get autocomplete and type-checking in definePageMeta.

<!-- layouts/panel.vue -->
<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  title?: string
}>()
</script>

📖 Read more: Layouts

🗣️ useAnnouncer Composable

Accessibility got a major boost with the new useAnnouncer composable and <NuxtAnnouncer> component (#34318). While useRouteAnnouncer handles page navigation for screen readers, many apps need to announce dynamic in-page changes – form submissions, loading states, search results, and more.

<!-- app.vue -->
<template>
  <NuxtAnnouncer />
  <NuxtRouteAnnouncer />
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

<!-- components/ContactForm.vue -->
<script setup lang="ts">
const { polite, assertive } = useAnnouncer()

async function submitForm() {
  try {
    await $fetch('/api/contact', { method: 'POST', body: formData })
    polite('Message sent successfully')
  }
  catch (error) {
    assertive('Error: Failed to send message')
  }
}
</script>

Note: This is part of our accessibility roadmap. You don't need to use it everywhere – for many interactions, moving focus to new content or using native form validation is sufficient. useAnnouncer is most useful when content changes dynamically without a corresponding focus change.

📖 Read more: useAnnouncer

🚀 Migrate to unrouting

We've migrated Nuxt's file-system route generation to unrouting (#34316), which uses a trie data structure for constructing routes. The cold start is roughly the same (~8ms vs ~6ms for large apps), but dev server changes are up to 28x faster when you're not adding/removing pages, and ~15% faster even when you are.

This also makes route generation more deterministic – it's no longer sensitive to page file ordering.

🍫 Smarter Payload Handling for Cached Routes

When a cached route (ISR/SWR) is rendered at runtime with payload extraction enabled, the browser immediately fetches _payload.json as a second request – which triggers a full SSR re-render of the same page. In serverless environments, this can spin up a second lambda before the first response has even finished streaming.

This release addresses this with two changes (#34410):

1. A new payloadExtraction: 'client' mode that inlines the full payload in the initial HTML response while still generating _payload.json for client-side navigation
2. A runtime in-memory LRU payload cache so that _payload.json requests can be served without a full re-render

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    payloadExtraction: 'client',
  },
})

Note: payloadExtraction: 'client' will become the default with compatibilityVersion: 5. The runtime cache is active for all users.

📖 Read more: Experimental payloadExtraction

🍪 refresh Option for useCookie

If you're using cookies for session management, you've probably run into the problem of needing to extend a cookie's expiration without changing its value. The new refresh option makes this simple (#33814):

const session = useCookie('session-id', {
  maxAge: 60 * 60,
  refresh: true,
})

// Extends expiration each time, even with the same value
session.value = session.value

📖 Read more: useCookie

♻️ useState Reset to Default

useState and clearNuxtState now support resetting to the initial value instead of clearing to undefined (#33527). This aligns with how useAsyncData handles resets and is more intuitive for state management.

const count = useState('counter', () => 0)
count.value = 42

// Resets to 0 (the init value), not undefined
clearNuxtState('counter')

📖 Read more: clearNuxtState

🕵️‍♂️ Better Import Protection

Inspired by features in TanStack Start, import protection now shows suggestions and a full trace of where a problematic import originated (#34454). This makes it much easier to debug why a server-only import ended up in your client bundle.

For example, if you accidentally import from a server route in a component:

The trace shows the import chain (the component was imported from a page), the exact line of code, and actionable suggestions for how to fix it.

We plan to continue work on improving our error messages. 🪵

🔮 View Transitions Types

You can now define view transition types in Nuxt's experimental view transitions support (#31982). This lets you use different transition styles for different navigation patterns (forwards vs. backwards, tabs vs. pages, etc.).

📖 Read more: View Transitions API

💡 Improved optimizeDeps Hints

When Vite discovers new dependencies at runtime and triggers page reloads, Nuxt now shows a clear, copy-pasteable nuxt.config.ts snippet to pre-bundle them (#34320). It also warns about unresolvable entries at startup.

🏷️ Normalised Page Component Names (Experimental)

A new experimental option normalises page component names to match route names (#33513), which can help with consistency in devtools and debugging.

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    normalizeComponentNames: true,
  },
})

📖 Read more: normalizeComponentNames

⚡ Build Profiling

Ever wondered where your build time goes? You can now get a detailed performance breakdown of your Nuxt builds (#34468, nuxt/cli#1243):

nuxt build --profile

This produces a report showing duration, RSS delta, and heap delta for every build phase, module, and bundler plugin:

![Build timings rep...

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)

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)

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.

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

📦 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.

🚫 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)

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.

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

📦 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.

🚫 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)

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)

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.

👉 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)

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)

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)

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)