The biggest improvement in this release is how mocking works. Nuxt initialization has been moved from setupFiles to the beforeAll hook (#1516), which means vi.mock and mockNuxtImport calls now take effect before Nuxt starts. This fixes a long-standing issue where mocks for composables used in middleware or plugins wouldn't apply reliably (#750, #836, #1496).
On top of that, mockNuxtImport now passes the original implementation to the factory function (#1552), making partial mocking much more natural:
registerEndpoint now works correctly with query parameters in URLs (#1560), and endpoints registered in setup files are no longer lost when modules reset (#1549).
@nuxt/test-utils v4 contains a few breaking changes, almost all related to requiring at least vitest v4 as a peer dependency (if you are using vitest). It replaces vite-node with Vite's native Module Runner and simplifies pool configuration.
This will mean improvements for test performance and mocking, but does require some changes to your test code.
!TIP
Most of the changes below are straightforward. The biggest thing to watch out for is code that runs at the top level of a describe block — see below.
This is the change that might require most change in your tests. Because we've moved the nuxt environment setup into beforeAll, this means composables called at the top level of a describe block will fail with [nuxt] instance unavailable.
// Before (worked in vitest v3)
describe('my test', () => {
const router = useRouter() // ran lazily, after environment setup
// ...
})
// After (vitest v4)
describe('my test', () => {
let router: ReturnType<typeof useRouter>
beforeAll(() => {
router = useRouter() // runs after environment setup
})
// ...
})
This applies to useRouter(), useNuxtApp(), useRoute(), and any other Nuxt composable or auto-import.
!TIP
If you only need the value within individual tests, beforeEach or directly within the test works too.
If you use vi.mock with a factory function, accessing an export that the factory doesn't return will now throw an error instead of silently returning undefined.
// Before: accessing `bar` would silently return undefined
vi.mock('./module', () => ({ foo: 'mocked' }))
// After: accessing `bar` throws
// Fix: use importOriginal to include all exports
vi.mock('./module', async (importOriginal) => ({
...await importOriginal(),
foo: 'mocked',
}))
!NOTE
If you're mocking a virtual module (like #build/nuxt.config.mjs) where importOriginal can't resolve the real module, you might need to explicitly list all accessed exports in your mock factory.
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.
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.
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.
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
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.
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.
pages/(protected)/dashboard.vue
<script setup lang="ts">
// This page's meta will include: { groups: ['protected'] }
useRoute().meta.groups
</script>
Module authors can now use async functions when adding build plugins (#33619):
modules/my-module.ts
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.
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)
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.
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:
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 routes (learn more).
While we recommend keeping this enabled for better type safety, you can disable it if needed:
npx nuxt upgrade --dedupe
# or, if you are upgrading to v3.21
npx nuxt@latest upgrade --dedupe --channel=v3
This will deduplicate your lockfile and help ensure you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.
!TIP
Check out our upgrade guide if upgrading from an older version.
Nuxt 4.3 and 3.21 bring powerful new features for layouts, caching, and developer experience – plus significant performance improvements under the hood.
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.
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.
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.
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
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.
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.
pages/(protected)/dashboard.vue
<script setup lang="ts">
// This page's meta will include: { groups: ['protected'] }
useRoute().meta.groups
</script>
Module authors can now use async functions when adding build plugins (#33619):
modules/my-module.ts
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.
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)
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.
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:
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 routes (learn more).
While we recommend keeping this enabled for better type safety, you can disable it if needed:
This will deduplicate your lockfile and help ensure you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.
!TIP
Check out our upgrade guide if upgrading from an older version.