@nuxt/schema

v4.6.2 is the next patch release.

Changelog

compare changes

Fixes

• nitro: apply useHeadSafe rules to server island head

• nitro-server: read router params from the path h3 matched

• nitro: match server route rules case-insensitively unless routing is sensitive

• nuxt: resolve rooted paths through the URL parser

• nuxt: resolve empty route types in shared context

• nitro: preserve server tsconfig with relocated build dir

• nuxt: fix scroll offset for IDs starting with numbers

• kit: do not exclude module directories with a dot in their name from app tsconfig

• nuxt: detect vapor slots with rawVaporSlotKey from vue

• nuxt: keep middleware layout when restoring deferred prerendered route

• schema: provide default value for experimental.typescriptPlugin

• vite: only replay compile error overlays to newly loaded pages

• nuxt: re-export AnyFetchPath for emitted server route types

• vite: warm up the dev ssr entry from a nitro plugin

• nitro: avoid unused h3 imports in nuxt/server runtime

• vite-server: scope asset url helpers to the build

• nuxt: resolve nuxt/app to the app's runtime

• kit: lowercase filename-derived handler method on nitro v2

• nuxt,nitro: normalise string/array appMiddleware

• nitro: pass response headers to render:response listeners

• vite: resolve inlined vue to its bundler build in dev

• nuxt: don't start a page transition with no page to leave

• nuxt: preserve error state on aborted or cancelled navigation

• vite,nitro: link null-byte virtual css through /@id/ in dev

• kit: resolve module dependencies from the declaring module

• nitro: only disable h3 + nitro presets when nitroAutoImports is off

• nitro,vite: don't access unspecified dependencies

• nitro: don't inline deps under absolute transpile dirs

• vite-server: respect spa loading template location

v4.6.1 is the next patch release.

Changelog

compare changes

Performance

• nitro: build the portable event's web view on first access

Fixes

• vite: match vite 8.1+ optimizer messages for deps hint

• nuxt: accept any baseURL when fetch response type is named

• nitro: resolve nitropack/types declarations under nodenext

• nuxt: allow false in setPageLayout types

• nuxt: align Serialize object types with JSON

• vite: don't abort dep scan on virtual imports in installed packages

• nuxt: update publishConfig config export extension

• kit: install the package a missing subpath belongs to

• vite-server: use the configured outDir as the public directory for non-ssr environment

• kit,nitro: match dev handler paths on both nitro majors

• nuxt: preserve onServerPrefetch for useId hydration

• vite-server: include the request in dev error reports

• nitro: register each dev server handler once

• nitro: pass RequestEvent to nuxt dev server handlers

• nuxt: type the global $fetch with nuxt's TypedFetch

• vite-server: work with deploy target plugins in dev

• schema: ignore .wrangler directory

• vite-server: pass the path to the error page render

• nuxt,vite: disable dev error broadcast if BroadcastChannel throws

• kit: align semantic version regexp with nightly version format

• nuxt: export types reachable from async data composables

• vite: detect enclosing string delimiter in inline style urls

• schema: type the nuxt dev server handler variant

• nitro: inline nuxt runtime when resolved to windows paths

• nitro: resolve unhead from nuxt in server bundle

v4.6.0 is the next minor release.

Some news

Nuxt CLI v4

Alongside the release of Nuxt v4.6, today also brings a new major release of the Nuxt CLI: @nuxt/cli v4. It ships as a dependency of nuxt, so you'll get it automatically when you upgrade.

Most of what's new is in nuxt dev:

• an interactive terminal UI, showing URLs, startup progress and keyboard shortcuts, with panels to dive into error logs, routes, network requests and more

• the dev server gives you more info, such as why it reloaded or restarted, which nuxt.config keys changed, where the time went during a slow start or build, and how long each module took to set up

• a CLI-level error channel rendered with my-bad (see below), powering things like automatically reloading when a syntax error in nuxt.config.ts is fixed

• a lock file in .nuxt/, which lets a second nuxt dev (say, one started by an agent) take over or defer to the one you started, and powers new nuxt curl and nuxt task commands that talk to the running server

There's also a new nuxt docs "<query>" search, and nuxt preview --takeover can replace a running preview server. And in general nuxt/cli is a lot smaller and starts a lot faster:

Although this is a major version, none of the changes should be breaking for Nuxt v4 users: we require Node.js v22.21+, v24.11+ or v26+, we drop nuxt init and only support npm create nuxt@latest, and Nuxt 2 and @nuxt/bridge are no longer supported.

👉 Check out the full Nuxt CLI v4 release notes for everything that's changed.

A server-agnostic Nuxt

The biggest thing about this release is our move towards making Nuxt server-agnostic.

I feel that freedom of choice is very much a fundamental value of the web, and one that unites the whole Nuxt team.

You can use pages/ (with vue-router) or not. You can use Vite, webpack or Rspack to bundle your code. You can pick from dozens of providers to deploy to, pick any image or font provider, choose any database adapter. In every case, the framework is the same.

The server side was different. #app composables imported h3 types, server code imported from h3 and nitropack, and every module that touched the server was tied to whichever major version of those packages Nuxt happened to depend on.

This has become particularly clear as we have been upgrading to new majors of h3 and nitro, which ship breaking changes with a cascading effect throughout the whole ecosystem.

👉 This release changes that.

Alongside explicitly defining our public API in nuxt/kit (which now does not refer to external packages), Nuxt now specifies our own types for the request event, route rules and typed $fetch, and we expose an import surface (nuxt/server) for the server utilities that will be needed by most apps.

This is the culmination of work we started almost a year ago, making it possible to use any server builder with Nuxt, not just Nitro (#33462).

Of course, under the hood, nuxt/server is still powered by Nitro by default - though we are also announcing a second, experimental implementation, @nuxt/vite-server, which allows pure-Vite server builds using the Vite Environment API.

[!IMPORTANT]
We believe that Nitro is still the right choice for almost everyone.

🌟 We see a number of key benefits for nuxt/server.

1. it smooths the upgrade to Nuxt 5, which moves to Nitro v3 and h3 v2. Server code written against nuxt/server on 4.6 runs unchanged there, so a module can ship one file for both.

2. it decouples Nuxt from the Nitro release cycle. Because we 'own' the API, we can adapt to breaking changes in Nitro or h3 without requiring a future major - and we can release Nuxt majors without having to wait for upstream releases.

3. it makes Nuxt's code more maintainable. It helps us preserve the separation of concerns between our API - /app and /server - and the bundler + server that you ultimately want to build your app.

... and there are a number of other benefits too, from a single type surface to being able to iterate more quickly on features.

Finally, I want to say a special thank-you to @pi0, whose relentless focus on server agnosticism and work on h3, Nitro and web-standard server primitives over the last few years is what makes a portable RequestEvent possible at all. Thank you, Pooya. ❤️

Almost every feature in this release is already in the Nuxt 5 branch, and most of the remaining Nuxt 5 defaults can be tested today with future.compatibilityVersion: 5 (more details below!).

[!TIP]
Nuxt 3 reached end-of-life on July 31, 2026, so there is no 3.x release alongside this one. If you're still on v3, the upgrade guide is waiting for you.

Highlights

🤷 If you've read this far I'm afraid I have bad news for you: there's a lot more still to say! Nuxt 4.6 is one of our biggest minor releases, with over 420 commits since v4.5.2.

... so, you might want to grab a coffee! ☕️

nuxt/server

It has been asked for for a long time, and it now exists (#36275)!

nuxt/server is a new import source for server code: handlers, middleware and utilities - a complement to nuxt/app. Where nuxt/app is for the part of your application that also runs in the browser, nuxt/server is for the part that only runs on the server.

import { defineEventHandler, getQuery } from 'nuxt/server'

export default defineEventHandler((event) => {
  const { name } = getQuery<{ name?: string }>(event)
  return { message: `Hello, ${name ?? 'world'}!` }
})

The utilities use web standards and are typed against a portable RequestEvent:

event.req         // Request
event.url         // URL
event.res         // { status, statusText, headers }
event.res.headers // Headers
event.context     // per-request context

Under @nuxt/nitro-server they are backed by Nitro and h3, but you never import from either.

So the same handler runs under Nitro v2, Nitro v3 or @nuxt/vite-server, and a module that imports from nuxt/server doesn't need a peer dependency on h3 or nitropack.

We think this will make a big difference in smoothing out the upgrade to Nuxt v5 and Nitro v3.

There is a typing benefit too. We no longer hoist h3 or Nitro types into your app to type useRequestEvent, $fetch or route rules, which removes a source of type conflicts when versions differ (#36212, #36214, #36293).

The surface is small, and covers what published modules and user code typically need: defineEventHandler, createError/isNuxtError, request URL, headers, query, body (plain and validated with any Standard Schema library or a function), cookies, redirects, response status, getRouterParam(s), getRequestIP, handleCors, getRouteRules, useRuntimeConfig, useAppConfig and sessions.

import { defineEventHandler, readValidatedBody } from 'nuxt/server'
import { z } from 'zod'

export default defineEventHandler(async (event) => {
  const user = await readValidatedBody(event, z.object({ name: z.string() }))
  return { created: user.name }
})

We encourage you to use web APIs (event.req.headers, for example), or raise an issue if there's functionality you're missing from nuxt/server 🙏

If you do need to step outside nuxt/server for a particular handler, don't worry! Nothing has been taken away: import defineEventHandler and the helpers you need from h3 or nitropack/runtime as before, and that handler works exactly as it did on Nuxt 4.5.

import { defineEventHandler, readMultipartFormData } from 'h3'

export default defineEventHandler(async (event) => {
  const parts = await readMultipartFormData(event)
  return { received: parts?.length ?? 0 }
})

[!IMPORTANT]
On Nuxt 4, the auto-imported defineEventHandler, getQuery, readBody and the rest are still h3's own helpers, which take a different shape of event. Import from nuxt/server explicitly, including defineEventHandler to use the new server runtime. If you mix the two, you'll see a NUXT_E8012 error which should tell you which import to change.

A few helpers also behave differently from their h3 v1 namesakes: sendRedirect returns the response rather than sending it, createError takes status and statusText, and response headers are set through event.res.headers. The upgrade guide has a table of the differences.

Nothing in this release requires a migration. But if you have server code you'd like to make portable ahead of Nuxt 5, this is the best way.

👉 Read the server imports guide.

appSecret and sessions

Nuxt now has a root application secret: runtimeConfig.appSecret, set with NUXT_APP_SECRET (#35874, thanks to @onmax). Modules and server features derive purpose-specific secrets from it with deriveSecret(purpose), so NUXT_APP_SECRET is the only secret you need to configure.

openssl rand -base64 32

In development Nuxt generates and persists one if none is configured (and warns the first time a derived secret is used). Builds never generate one.

The first thing to use it is a set of session helpers in nuxt/server (#36358). Sessions are sealed into a cookie with iron, so there's no server-side storage to configure:

import { defineEventHandler, useSession } from 'nuxt/server'

export default defineEventHandler(async (event) => {
  const session = await useSession<{ visits: number }>(event)
  await session.update(data => ({ visits: (data.visits ?? 0) + 1 }))
  return { visits: session.data.visits }
})

[!NOTE]
As a reminder, runtime config keys prefixed with app (runtimeConfig.app, runtimeConfig.appSecret) are reserved for Nuxt.

Typed $fetch, rebuilt

$fetch and useFetch have been typed from your server routes for a long time. But the types were derived from Nitro's InternalApi interface, and past a few hundred routes they hit TypeScript's instantiation limit with the familiar TS2589: Type instantiation is excessively deep and possibly infinite.

We've rebuilt typed fetch on top of fetchdts (#36238). Nuxt compiles your server routes into a route tree with an exact-match table for static paths and accessors specialised to your route set. Resolution cost now scales with call sites, not with route count:

Peak memory for the same runs dropped from 946 MB to 140 MB. 🔥

Plus, the route set also carries the body, query and headers a handler validates, so calls are checked more tightly than before:

// server/api/users.post.ts validates { title: string, count: number }
await $fetch('/api/users', { method: 'post', body: { title: 'a', count: 1 } })
await $fetch('/api/users', { method: 'post', body: { title: 'a', count: 'no' } })
//                                                                ^ not assignable to number
await $fetch('/api/users', { method: 'post' })
//           ^ body is required

On Nuxt 4 this is opt-in, because there are small changes to type inference, and hand-written ServerRoutes augmentations need a small rewrite. It is the default in Nuxt 5.

export default defineNuxtConfig({
  experimental: {
    routeTypedFetch: true,
  },
})

There's also a new experimental.strictRouteTypes option to reject calls to paths that don't exist (otherwise these just return unknown), and an 'isomorphic' mode that types your pages as GET routes too if you want to be able to $fetch from the Vue renderer with type safety.

👉 Read more in the experimental features docs.

Better errors in development with my-bad

Server-side errors in development used to look like this:

ReferenceError: foo is not defined
    at Object.<anonymous> (/_nuxt/app/pages/index.vue:1:1)

There was no source position or code frame, and the Youch iframe we rendered could not show you the frame in your own source either. Both are now fixed (#36258, nuxt/cli#1518).

Dev SSR stack traces are now mapped before anything reads the error, and the Youch overlay has been replaced with my-bad. It renders into your app's own error page as an overlay (or as a standalone page when the app can't render one), with the mapped stack trace and a code frame from your source, and the same report is printed in your terminal. We are still working with @atinux, @HugoRCD and @antfu to make these pages nicer still.

With Nuxt CLI v4, there is a single live error channel at the CLI level. It survives worker restarts, so (for example) a syntax error in nuxt.config.ts will live-reload the page once you fix it. Each error is rendered once rather than at every layer it passes through, and the same channel streams build progress and app logs to the dev panel.

A new loading screen, 404 and error pages

@HugoRCD has redrawn the loading screen you see while the dev server starts. It is now a WebGL2 particle field that traces a mountain range behind the Nuxt lockup (#36178), using a single shader and a single draw call. Without WebGL2 it falls back to the static lockup, and with prefers-reduced-motion the animation stops. Try hovering over it. 🏔️

Hugo also gave the built-in 404 and error pages a neutral palette and lighter type (#36255), and @MirkoJa added a back button to the 404 page (#35688).

Vue Vapor support

Nuxt now supports Vue 3.6's Vapor Mode in interop mode (#35759). Your app root stays on the virtual DOM, and you can opt individual components or pages into Vapor by adding the vapor attribute to <script setup>:

export default defineNuxtConfig({
  vue: {
    vapor: true,
  },
})

<script setup vapor lang="ts">
const count = ref(0)
</script>

<template>
  <button @click="count++">
    count is {{ count }}
  </button>
</template>

Routing, useAsyncData, layouts and most built-in components keep working unchanged. Along the way we made the auto-import loader, useAsyncData, definePageMeta and slot inspection Vapor-aware, and we now have a Vapor test suite so we can track what's supported.

[!NOTE]
This requires Vue ^3.6.0-rc.2 or newer. See the known limitations and try it in a fresh project first.

Addons for useFetch and useAsyncData

@cernymatej has added an addons option to the createUseFetch and createUseAsyncData factories (#35797). An addon can declare custom call-site options, adjust the merged options, wrap the handler with middleware, and extend what the composable returns, and it can be reused across as many custom instances as you like.

const refreshOnFocus = defineUseFetchAddon({
  setup: (options: UseFetchAddonOptions<{ refreshOnFocus?: boolean }>) => {
    if (import.meta.server || !options.refreshOnFocus) { return }

    return (asyncData) => {
      const focused = useWindowFocus()
      watch(focused, focused => focused && asyncData.refresh())
      return { focused }
    }
  },
})

export const useApiFetch = createUseFetch({ baseURL: '/api', addons: [refreshOnFocus] })

<script setup lang="ts">
const { data, focused } = await useApiFetch('/todos', { refreshOnFocus: true })
</script>

This resolves a long list of feature requests for useAsyncData and useFetch (refresh on focus, polling, retries, auth headers and more) without making the core composables opinionated about any of them.

👉 Read about defineUseFetchAddon and defineUseAsyncDataAddon.

Performance

There is a lot of performance work in this release.

• <NuxtLink> renders 58% faster on the server (#36015). Internal links are now rendered as a plain <a> with no useLink, no computed and no reactive state. Rendering 200 links went from 1.36ms to 0.57ms, which is 1.4x faster than a bare <RouterLink>.

• Early 404s (#36117). With experimental.early404, page routes are compiled into a static matcher at build time and requests that can't match any page skip creating the Vue app, running plugins and middleware entirely. On an app with 30 pages and ~23ms of boot work per render, a JSON 404 went from 37.1ms to 0.3ms.

• Templates declare their dependencies (#35875). The virtual file templates used in Nuxt's build used to regenerate on every file change. They now declare what invalidates them, so editing a component regenerates 0 of 49 core templates instead of all of them, and the builder:watch hook settles in 0.6ms instead of 36ms.

• Cookie jars (#36114). useCookie parses the cookie header once per request (or once per microtask on the client) instead of on every call. A nice side effect: a cookie set in a plugin during SSR can now be read by a later useCookie in a page.

• ssr: false pages are tree-shaken from the server bundle (#35836, thanks to @Austin1serb).

• Serializable definePageMeta keys are extracted at build time (#35919), behind experimental.extractSerializablePageMeta.

• Faster dev server warm-up: Vite's server module graph is warmed before the client (#36154), the client graph is crawled during warm-up (#35870), and warm-up yields to your first navigation so it never competes with a real request (#36412).

• Smaller client bundle: unctx is no longer shipped to the browser and defu is skipped for a single app.config (#36371).

• Fewer dependencies: @nuxt/kit no longer depends on c12, untyped, confbox, pkg-types, ufo or mlly, and jiti and giget are now optional peers loaded only when needed (#35936, #35943, #35946, #36071, #36073, #36083).

• Lazy impound tracing for builds (#36172), virtual module hooks filtered by id (#36077), isVue checks migrated to plugin filters (#36116) and an flru prerender cache (#36340).

Put together, on our benchmark machine (arm64 Linux, Node 24.15, medians of 5 runs):

Dev server start-up (spawn to first HTML) on the same machine is about 12% faster on a starter app, with the second request served in roughly half the time, though the CLI major changed alongside so not all of that is Nuxt.

Lighter payloads

useAsyncData and useFetch accept a serialize: false option to keep data out of the __NUXT_DATA__ payload (#35779). That's most useful inside components that never hydrate, and experimental.stripNeverHydratedData applies it automatically to data fetched within hydrate-never component trees.

Nuxt also warns in development when a page's payload exceeds 100 kB (#35777) and when a route rendered with noScripts relies on client-side JavaScript (#35780), and noScripts pages keep their non-script resource hints and attach their styles correctly (#35803, #36356, #36359).

<NuxtLink> now prefetches server-page islands (#35808), and @atinux made prefetch hints throttled and prioritised so a page full of links doesn't flood the network (#36261, #36324). Building on that, route chunks, layouts, middleware, payloads, islands and resource hints all now go through one client prefetch scheduler with per-kind concurrency caps, deduplication by key, and cancellation of in-flight work when you navigate away (#36391).

Nuxt 5 features, today

Most of what's new in Nuxt 5 is already in 4.6, either as the default or behind a flag. future.compatibilityVersion: 5 turns on the Nuxt 5 defaults in one go, and every one of them can be enabled (or disabled) individually.

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

Newly gated behind the flag in this release:

• Typed pages (experimental.typedPages)

• Typed $fetch (experimental.routeTypedFetch), described above

• Case-sensitive routing, matching Nitro (#35650, thanks to @Mateleo)

• Early return from navigateTo (experimental.navigateToEarlyReturn): navigateTo in <script setup> short-circuits the rest of the setup, so redirects and 404s don't throw on missing data

• Serializable page meta extraction (experimental.extractSerializablePageMeta)

• Client-side payload extraction (experimental.payloadExtraction: 'client')

• Normalized page names, clearNuxtState resetting to defaults, experimental.watcher: 'builder', and no auto-imported server-only head composables

• No baseUrl in generated tsconfigs (#36040, thanks to @oritwoen)

• Inline error rendering (experimental.inlineErrorRendering): when a server render fails, error.vue is rendered in the same request with a plain try/catch, instead of re-entering the server over an internal request to /__nuxt_error. Headers and cookies the failed render had already set are kept, error renders no longer pass through Nitro middleware and route rules a second time, and render:html fires with the original event (#36399).

The upgrade guide now lists exactly what the flag changes on Nuxt 4.

Experimental: @nuxt/vite-server

Since v4.2 server.builder has been configurable. This release adds a second server builder: @nuxt/vite-server. It builds a Nuxt app with Vite alone (#36218, #36279, #36288).

This is all you need to do to configure it.

export default defineNuxtConfig({
  server: {
    builder: 'vite', // 'nitro' is the default
  },
})

It can produce a pure client SPA, a server-rendered app with a small Node entry, a web-standard fetch handler for platforms that provide the server (there are e2e examples for Cloudflare Workers, Netlify and universal deploy), as well as fully static output with nuxt generate.

Right now, this helps keep Nuxt's code agnostic, enforce the contract behind nuxt/server, and to give Vite plugins that provide a deploy target something to build on. It does not have Nitro's full feature set (there is no storage, caching, tasks or server plugins), and we expect most apps to keep using Nitro. Nitro remains the default.

[!WARNING]
This is highly experimental and the API will change. 'nitro' and 'vite' are new shorthands for @nuxt/nitro-server and @nuxt/vite-server.

Developer experience

• Clickable file paths in terminal output (#35898). Warnings that mention a file now link to it in your editor, at the line responsible where we know it.

• IDE hover docs for built-in components (#35701). Hovering a built-in component like <NuxtLayout> or <NuxtLink> in a template now shows a short description and a link to the docs. Thanks to @Ibochkarev.

• app/types/ and server/types/ are included in the right tsconfig, so ambient types and augmentations placed there are picked up (#35783, thanks to @Flo0806, who also added an augmentable NuxtPageMeta for typing NuxtPage.meta in #34816).

• Grouping folders in components/: a (group)/ folder is excluded from the component name (#35699, thanks to @abaza738).

• Dynamic expires in useCookie, accepting a function (#35628, thanks to @DarlanPrado).

• A warning when a public/ file shadows an application route (#35674, thanks to @Norbiros).

• Install hints use your package manager (#35871).

• Prerender your error pages as real HTML (404.html, or any status codes you pass) with experimental.prerenderErrorPages instead of an empty SPA shell (#35193, thanks again to @Flo0806).

• $Fetch is exported from nuxt/app (#35625) and ShallowRef is in the Vue auto-import preset (#36266), both from @DamianGlowala; preloadComponents and the NuxtIsland name prop are typed (#35775), and useLayout, useLoadingIndicator and useRequestHeader are exported from nuxt/app (#36033).

• typescript.tsConfig is now a shared baseline for all four generated tsconfigs, with appTsConfig and serverTsConfig for per-context overrides (#35697, thanks to @chairulakmal).

• Top-level prerender option, an alias for nitro.prerender in the same way runtimeConfig and routeRules are top-level (#32356). Nuxt now also points you towards top-level options where they exist, since those work across server builders (#36416).

• Links to public/ files just work. If the router has no route for a <NuxtLink> target (a PDF in public/, say, or a link from Markdown with Nuxt Content), Nuxt falls through to a full-page load instead of rendering your 404, so external is no longer required (#36169).

• Renaming a component in development refreshes its imports, so you no longer see stale references to the old file (#36165, thanks to @oritwoen).

• Layers: dependencies of layers installed from node_modules are pre-bundled by Vite (#36208), and symlinked layer directories resolve to their real path (#36402, thanks to @silverbackdan).

For module authors

If you maintain a module with server code, we've enabled making modules compatible with both Nuxt 4 & 5, without requiring a major bump. (And we'll be opening PRs proactively after the release of Nuxt v4.6 to assist with preparing for a Nuxt v5 release...)

• One module for Nuxt 4 and Nuxt 5. addServerHandler, addDevServerHandler and addNitroPlugin accept a map of variants per server API (#36317). Nuxt chooses the most appropriate one. A handler that imports only from nuxt/server needs no Nitro 2/3 variants at all (but does require Nuxt v4.6+).

  addServerHandler({
    route: '/api/my-module/status',
    handler: {
      nuxt: resolve('./runtime/server/status'),
      nitro2: resolve('./runtime/server/status.legacy'),
    },
  })

  Nuxt reads the file's imports to decide which API it uses. Where that isn't enough, you can declare meta.compatibility.server. getNitroVersion and hasNitroVersion are also there in case you have logic that explicitly requires you to know the Nitro version installed (#36127).

  👉 Read the server compatibility guide for more information.

• Nuxt-owned, augmentable server types: ServerTypes, ServerRoutes, AppRouteRules and NuxtRequestContext. Augment @nuxt/schema once; nuxt/schema mirrors it (#36293).

• useTerminal for host-aware prompts, status messages and tasks in progress, rendered by the CLI's dev panel when there is one (#36162).

• module:before and module:done hooks, which Nuxt CLI v4 uses to show per-module setup time as it happens (#36173).

• onConfigResolved and diffNuxtConfig to see what changed between two config loads (#35853).

• ensureDependencyInstalled and getAddDependencyCommand to check for and offer to install optional dependencies with the user's package manager (#34554).

• Template dependencies to say exactly what should invalidate a template (#35875).

• addServerImports, addServerImportsDir and addServerTemplate work the same across Nitro versions; a server tsconfig and versioned route config types are generated for you (#36265).

• @nuxt/kit has an explicit public API (#36074) and @nuxt/schema is an optional peer (#36246).

• Modules can now set experimental.asyncContext (#36175, thanks to @cernymatej), Vite plugins added via kit land at the top level rather than wrapped (#36037), and more build-time warnings have moved to diagnostic codes with docs pages (#36138).

• @nuxt/kit peer dependency ranges are widened to the versions actually required rather than tracking the latest of each package (#36417), and updateRuntimeConfig no longer warns when called before Nitro exists (#36403, thanks to @Neekoras).

Security

• security

  The internal error route is only served to an error render, and can no longer be reached from outside (259058cf4, #36305).

• security

  Dev error reports are scoped for remote peers, and the dev error channel is kept out of production builds (#36389, #36407).

• security

  Unhandled error data is no longer passed to the error page (38a40cfc0), oversized island bodies are drained before being rejected (#36320), and error-render recursion is tracked in request context rather than via a client-controllable header (d8c729435).

Important fixes

• Awaited useAsyncData no longer resolves with unfetched data on hydration (#36124), awaited lazy async data resolves immediately (#36301), and useAsyncData types resolve for generic type params (#36316).

• useRequestFetch forwards request headers (#36180, thanks to @hdwebpros).

• navigateTo matches vue-router's path encoding (#36055), preserves percent-encoding in server redirects (#36112), and applies baseURL with open (#36197).

• Scoped styles apply to server component slots (#36047), island asset requests are deduped (#36048), lazy hydration no longer produces blank remounts (#36051), all from @oritwoen, and hydrated nuxt-client markup is stripped from cached island HTML (#36298).

• A batch of CSS fixes across Vite, webpack and rspack: duplicate CSS links for inlined chunks (#36056), baseURL and url() rewriting in inlined styles (#36137, #36143), island descendant CSS extraction (#36260) and stable style chunk names (#36361).

• View transitions handle interrupted and skipped navigations (#35537 from @Askerka00, #36314), and page transitions stay mounted for nested routes with no children (#36304).

• The streaming shell head renders after the first render pass (#36120).

• Payload URLs are parsed as origin-relative paths, so a path like //x/_payload.json no longer serves the wrong payload (#36409, spotted

• /index.html is prerendered for client-only apps with islands (#36299).

• definePageMeta works at the top level of setup() (#36245), and changed auto-import sources are rescanned before their consumers (#33671, thanks to @Flo0806).

• A template that never finishes compiling now fails the build instead of exiting 0 (#36322).

• Error causes are preserved in development (#35632, thanks to @onmax).

• Layout onBeforeLeave reuses the pending transition promise (#36395), and baseURL and middleware flags are respected in apps without pages/ (#36034).

• stripNeverHydratedData no longer mutates the options object (#36035), the dev error module is stubbed out of production builds (55e61d75d), and preloading a component that is not global now warns (47de80ece).

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, including Nuxt CLI v4.

[!NOTE]
This release requires Node.js ^22.22.3 || ^24.15.0 || >=26.0.0.

If you have server code you'd like to make portable, read Moving to nuxt/server in the upgrade guide.

Changelog

compare changes

Enhancements

• kit: add resolveServerVariant + addServerImports variant support

• nuxt: add addon support to createUseFetch and createUseAsyncData

• vite-server: back serverFetch and route rules in nuxt/server

• nuxt,nitro,schema: add useServerHooks to nuxt/server

• nuxt,nitro: add serverFetch to nuxt/server

• nuxt,nitro: add forwarded url, cookie and route rule helpers to nuxt/server

• nuxt,vite: add hook, bundler and middleware tracing channels

• nuxt: serve unmatched public asset paths on client-side navigation

• nuxt,schema: add top-level prerender alias for nitro.prerender

• nuxt,vite-server: render the error page in the renderer itself

• nuxt: unified client prefetch scheduler

• nuxt: add useAppConfig to nuxt/server

• nuxt: add handleCors to nuxt/server

• nuxt: add readValidatedBody and getValidatedQuery to nuxt/server

• nuxt: add getRouterParam(s) and getRequestIP to nuxt/server

• nuxt,nitro,vite,vite-server: scope dev error reports for remote peers

• nitro,vite: map dev ssr stacktraces and render errors with my-bad

• ui-templates: use neutral palette and lighter error type

• ui-templates: particle mountain loading screen

• nuxt: add session utils to nuxt/server

• nuxt,schema: add nuxt appSecret

• nuxt: add server + client cookie jars to avoid unnecessary reads

• kit,nitro,schema: register server handlers and plugins per server API

• nuxt,nitro,vite-server: compile nuxt core route rules

• vite-server: support nuxt generate prerendering

• kit,schema,vite-server: render in a target's own env (+ add e2e tests)

• nuxt,schema: give nuxt/server handlers a portable event

• nuxt,kit,schema,nitro,vite-server: add nuxt/server

• kit: add a server tsconfig and versioned nitro route config types

• nuxt: add ShallowRef type to vue preset

• nuxt: type $fetch and useFetch from generated server routes

• kit,nuxt,vite,vite-server: add experimental pure vite server

• kit,schema: add module:before/module:done hooks

• kit: add useTerminal for host-aware prompts and tasks

• nuxt: add experimental early404 for unmatched page routes

• nuxt: add experimental early return after navigateTo

• kit: nitro version utils + version-tagged server utils

• nuxt: support vue vapor

• nitro: allow prerendering error page

• nuxt: use @nuxt/cli v4 prerelease

• nitro,nuxt: improvements when rendering with noScripts

• kit,nitro,nuxt,rspack,vite,webpack: use package manager in hints

• nuxt: make file names clickable 🖱️

• nitro: warn in dev when noScripts routes rely on client JS

• nitro,nuxt,schema: let templates declare dependencies

• nuxt: prefetch server page islands via <NuxtLink>

• kit: expose resolved config snapshot and diff helper

• nitro: warn in dev when payload exceeds 100 kB

• nuxt,nitro: auto-import types from app/types and server/types directories

• nuxt: type preloadComponents and NuxtIsland name

• schema: enable typedPages with compatibilityVersion: 5

• nuxt: add serialize option to keep async data out of payload

• ui-templates: add back button on 404 page

• kit: easier way to define global tsConfig options

• nuxt: log template write paths when debugging

• nuxt: export $Fetch type

• nuxt: add IDE hover docs for built-in components

• nuxt: support grouping folders in component directories

• schema: add augmentable NuxtPageMeta interface for NuxtPage.meta

• nuxt: warn when public files override application routes

• nuxt: support dynamic expires in useCookie

• schema: case-sensitive routing by default in v5

Performance

• kit: use package-manager-detector to install packages

• vite: stop serial-build warmup on first navigation

• vite: evaluate ssr entry before the first dev render

• vite-server: index public files only once

• nuxt: drop unctx from client environment (+ defu in single-object config)

• nitro: use flru for prerender cache

• nitro,nuxt: use lazy impound tracing for builds

• vite: warm the server module graph before the client

• nuxt,vite: migrate isVue calls into plugin filters

• kit: remove confbox and pkg-types from dependencies

• nuxt: filter virtual module load hooks by id

• kit: drop ufo dependency

• kit: use microdiff and node:crypto

• nuxt: render internal <NuxtLink> anchors directly on server

• nuxt,kit: avoid loading jiti unless it is needed

• nuxt: tree-shake ssr: false pages from server bundle

• nuxt: extract serializable definePageMeta keys at build time

• vite: crawl client module graph when warming dev server

Fixes

• nuxt: resolve anchor hrefs through the router

• nuxt: leave a newer async data entry alone when an old one is taken off

• nuxt: await async layouts before navigation

• nuxt,vite: show compile error overlay on client-only pages

• schema,vite-server: accept null from prerender ignore functions

• nuxt: keep CookieOptions compatible with cookie serialize options

• kit: point NUXT_B1022 at resolving templates before bundling

• kit: only write missing types when building into a relocated build dir

• kit,nuxt: preserve types when building into a relocated build dir

• nuxt,nitro: render html page errors + json server route errors

• nuxt,vite-server: keep cookies + respond to json clients on errors

• vite,nitro: rewrap console if build throws

• kit,nuxt: provide nuxt/internal/dev-error as a server runtime module

• nuxt: allow @nuxt/cli runtime imports in server runtime

• nuxt: type nitro type path helper with NitroConfig

• nuxt: refresh component imports after rename

• nuxt: skip browser notices without error in dev overlay

• kit: widen peer dependency ranges to supported versions

• deprecated

  schema: deprecate nitro.* options duplicated at the top level

• vite: pre-bundle deps of layers installed in node_modules

• nuxt: respect base URL and clear middleware flags without pages/ (#36034)\

• nuxt,nitro: stub dev error module in production builds

• nitro: do not warn for public asset dirs generated in the build dir

• nuxt: resolve @nuxt/* type paths from nuxt's own resolution

• nuxt: warn when preloading a component that is not global

• nitro: resolve nitro dependency types from the copies nitro uses

• nuxt: avoid mutating options when stripping never-hydrated data

• kit: do not warn when updateRuntimeConfig runs before nitro exists

• kit: resolve symlinked layer directories to their real path

• nuxt: reuse pending transition promise in layout onBeforeLeave

• vite: keep named compile report over nameless hmr payload

• nuxt: reject sealed values not issued by nuxt sessions

• nitro,vite: sort prerendered routes in app manifest

• nuxt: parse payload url as origin-relative path

• nitro: explain when an h3 event reaches a nuxt/server helper

• nuxt: invalidate auto-import consumers on the hmr-less ssr dev server

• nitro: give the portable event's response headers the full Headers interface

• nuxt: accept Endpoint-shaped ServerRoutes augmentations in the InternalApi engine

• nitro: keep dev error channel out of production builds

• nuxt: share client app context across module instances

• nitro: resolve path placeholders in nitro preview command

• nitro: extend nitropack runtime app config with nuxt fields

• nitro: detect an http error by brand in the dev error handler

• nuxt: explain nitro 2 env parsing when a derived secret is unusable

• nuxt: prepend the vite unctx transform so it reaches page-meta macro modules

• nitro: renumber duplicate NUXT_E8009 diagnostic code

• vite: await ssrFixStacktrace

• vite: keep deduped packages out of importer-based external resolution

• nuxt,vite: attach resources to pages served without scripts

• vite: share a style chunk-name counter across component extractions

• nuxt: keep non-script resource hints on noScripts routes

• nuxt: strip hydrated nuxt-client markup from cached island html

• nuxt: widen nuxt/server helper event types

• nuxt: keep a configured appSecret and warn when it is used

• nuxt: keep session managers in step after clearSession

• nuxt: use a throttle approach for hint prefetching

• kit: normalise method case when checking for duplicates

• kit: respect method when checking for existing handlers

• kit: register the base path of a wildcard route on nitro v2

• nitro: render streaming shell head after first render pass

• vite: skip client manifest finalisation for aborted builds

• nitro: apply server replacements to prerenderer

• kit,nuxt,schema: let a server build declare the module backing fetch

• kit,nitro: follow host nitro major in server build runtime fallback

• nuxt: apply nitro type paths in prepare:types in dev

• nuxt: forward request headers with useRequestFetch

• nitro: serve repeated reads of a nuxt/server request body

• nitro: write registered server plugins into the nitro config

• nuxt: resolve awaited lazy async data immediately

• nuxt: resolve useAsyncData type for generic type params

• nitro: drain oversized island body before rejecting it

• kit,nuxt: fail the build when a template never finishes compiling

• nitro: buffer the body read through a nuxt/server event

• nitro: scan a layer's server utils before the project's

• nitro: pass glob patterns to devStorage fs watch ignore

• nuxt: keep view transition state for interrupting navigations

• nuxt: handle rejected ready promise of skipped view transition

• nitro: serve the internal error route only to an error render

• nitro: guard internal error render on request context

• vite: resolve bare ssr externals from their importer

• nitro,vite-server: render error.vue 404 when accessing /__nuxt_error

• nuxt: skip scanning page meta if the scanner cannot parse

• nitro: prerender /index.html for client-only apps with islands

• nuxt: keep page transition mounted for nested route with no children

• nuxt: respect image prefetching as preload to respect Accept hea…

• nuxt: listen to link:prefetch hook before onNuxtReady

• vite: let the app build serve a server build that is not its own pass

• vite: let a server build that is not its own pass reach the app entry

• nitro: load nitropack in any program that augments it

• kit,nitro,schema: derive the fallback server runtime from the host nitro major

• nitro: do not pass unhandled error data to error page

• kit: declare @nuxt/schema as an optional peer dependency

• kit,nuxt,schema,vite-server: let vite plugins own the deploy target

• nuxt: avoid app config declaration conflicts

• nuxt: rescan changed auto-import sources before their consumers

• rspack,webpack: do not serve server bundle from dev server

• vite: extract css of island descendants when inlining is off

• kit: explicitly include .vue and other extensions tsconfigs

• nuxt: resolve layout hydration guard when unmounted early

• nuxt: bound island v-for on nuxt-client elements without selectiveClient

• nuxt: only rewrite island uid marker in attribute position

• nuxt: serialize numeric v-for island slot scopes 1-based

• nuxt: support definePageMeta at the top level of setup()

• nuxt: make target optional if calling navigateTo w/ open

• vite: exclude stable entry chunk from preload dependencies

• nuxt: apply baseURL when calling navigateTo with open

• nuxt: expose shallow async data ref

• nuxt: ignore grouping folders when collapsing repeated name segments

• nuxt: register namespace binding alongside default import

• nuxt: keep extracted __proto__ page meta keys as own properties

• nuxt: disable early 404 for page paths that cannot be decoded

• nitro: resolve aliases and rootDir-relative asset dirs

• nuxt: key dynamic meta by file path + nuxt instance

• schema: keep nuxt/schema augmentation bridge out of bundled types

• kit: forward configFile and rcFile to config loader

• nuxt: validate component export name before code generation

• nuxt: allow modules to set experimental.asyncContext

• schema: type import.meta.env as ImportMetaEnv

• kit,nitro,schema: ensure tsconfigs exist before build

• schema,nuxt: accept partial app config input + stop merging functions

• ui-templates: mark the loading page's poll as a document request

• ui-templates: back off the loading page's poll

• vite: rewrite every public asset url() in CSS

• vite: apply baseURL to public assets in inlined styles

• nuxt: resolve layout name override in layout isCurrent check

• nuxt: bridge AppConfigInput augmentations into nuxt/schema

• nuxt: don't resolve awaited useAsyncData with unfetched data on hydration

• nuxt: preserve percent-encoding in server navigateTo redirects

• nuxt: preserve regexp and function values when cloning import presets

• nitro: match exact nonce attribute for streaming CSP nonce

• nuxt: pass absolute paths to build cache ignore check

• nitro: preserve overlapping dynamic payload rules

• kit: retry CJS-global and alias load failures through jiti

• rspack,webpack: respect inlineStyles predicate for global css

• rspack,webpack: do not search filesystem for postcss config

• rspack,webpack: keep url() wrapper when rewriting inlined styles

• nuxt: hide internal dynamic page meta key behind a symbol

• nuxt: keep page bundle restrictions out of the pages array

• nuxt: avoid duplicate island asset requests

• kit: reorder diagnostics by code

• kit: retry nested load failures through jiti

• nuxt: keep <NuxtTime> locale prop reactive after hydration

• nuxt: validate scopeId prop passed to <NuxtIsland>

• vite,nitro: keep css links for unrendered components

• nuxt: apply scoped styles to server component slots

• kit,nitro: ignore baseUrl with compatibilityVersion 5

• nitro: in dev, only add css for islands actually rendered

• vite: drop duplicate CSS links for fully inlined shared chunks

• nuxt: match vue-router path encoding in navigateTo

• nuxt: avoid blank lazy hydration remounts

• nuxt: don't defer hydration route for trailing-slash-only diffs

• kit: add vite plugins at top level instead of wrapping them

• nuxt: keep ref-initialised useState connected to payload state

• nuxt: only compute distURL in development

• nuxt: export useLayout, useLoadingIndicator and useRequestHeader

• vite: recover throttled watcher changes in dev servers

• nuxt: only map test components for webpack and rspack

• nuxt,nitro: unwrap route rule matches when resolving rules

• nuxt: stub client-only components + map test components in server build

• nuxt: do not write readonly cookies on client

• nuxt: skip cookie watcher entirely when readonly

• nitro,nuxt: hoist route matcher to prevent temporal dead zone

• nuxt: resolve ufo from nuxt dependencies

• nitro: resolve paths pointing at bare module specifiers

• nuxt: preserve error causes in development

• nuxt: improve js type-checking

Refactors

• removed

  nuxt: remove config.cjs file in require export

4.5.2 is the next patch release.

Changelog

compare changes

Performance

• nuxt,kit: Skip rewriting unchanged generated files

• kit,nuxt: Use lazy imports to improve parsing speed

• vite: Skip html entry probes in bare-import resolver

• nuxt: Reuse app and component scans for unchanged structures

Fixes

• vite: Resolve client manifest path from resolved config

• nuxt: Use client-side navigation for links inside islands

• nuxt: Generate types for route params defined with definePageMeta

• nuxt: Serialize island payloads for components with underscores in keys

• nitro: Dedupe island renders when prerendering

• nuxt: Drop prefetch hints for never-hydrated chunks

• vite: Use same asset filenames for worker builds

• nitro: Reject non-object island props

• nuxt: Support options api in v-for islands transform

• nuxt: Improve page meta extraction + performance

• nuxt: Set build outputs when restoring vue cache

• kit: Honour nested apply and applyToEnvironment in vite wrapper

• nuxt: Re-check for preview mode after prerendered page hydration

• kit,nuxt,vite: Handle missed chokidar watch events

• nuxt: Settle asyncData status when bailing

• kit: Clone resolved config with klona rather than klona/full

• kit: Honour nested plugins' enforce in vite wrapper

• nuxt: Collect build cache once build outputs are final

• vite: Resolve vite env api sourcemaps in vite-node

• nuxt: Don't warn about missing <NuxtPage> on nav + with slot

• kit: Prepend vite environment wrapper plugin when prepend is set

• nuxt: Depend on rolldown as a peer to reuse vite's copy

• nitro: Define import.meta.test for server code

• nuxt: Match route rules against decoded paths

⚠️ This is a security release. We recommend upgrading as soon as possible with npx nuxt upgrade --dedupe.

It fixes server-side RCE and unauthorized component instantiation via server island props, a route rule authorization bypass, server component DoS, cross-user payload disclosure on cached pages, and dev server path disclosure. Refreshing your lockfile also pulls in @nuxt/devtools@3.3.1, which fixes a separate critical development-only RCE.

If you already upgraded for the earlier route rule advisory (CVE-2026-53721), you still need this release: one of the fixes addresses a regression introduced by that fix.

If you use the cache, swr or isr route rules, purge any CDN or edge cache after upgrading; a leaked _payload.json may already be cached upstream.

Full details: Nuxt Security Patch Releases and GitHub Security Advisories.

Changelog

compare changes

Performance

• nitro: Replace island teleports in a single html pass

• nuxt: Add vue.optionsApi and disable it for v5+

• nuxt: Without pages, skip client plugins that require routing

• nuxt: Skip payload revival plugin when ssr: false

Fixes

• nitro: Read rspack dev output fs lazily for server entry

• rspack,webpack: Resolve loaders and runtime deps from nuxt dirs

• nuxt: Return global route for useRoute in detached effect scope

• nuxt: Ignore custom name or path when reusing an existing page in pages:extend

• nuxt: Render client components in nested server components

• nuxt: Preserve explicit useFetch method inference

• nuxt: Revalidate cached route payloads instead of using force-cache

• nuxt: Correct default export detection in plugin metadata

• nuxt: Clear hide/reset timeouts in set()

• kit,nuxt,rspack,schema,webpack: Add .mts file extension in resolver

• nuxt: Preserve trailing slash in NuxtLink href when unset

• nuxt: Don't cross-pollute useAsyncData cache on reactive key change

• nuxt: Filter plugin dependencies by build target

• nuxt: Reload real page module on HMR of JSX render-function pages

• nuxt: Resolve @unhead/vue/* from nuxt's dependency tree

• kit: Surface module load errors instead of masking as missing

• nuxt: Type auto-imported $fetch with nitro's $Fetch

• nuxt: Don't reference app config sources in shared and node tsconfigs

• vite: Resolve SSR inlined CSS module class name mismatch

• nuxt: Generate layout types even when pages module is disabled

• nitro: Skip resource hints for stylesheets already rendered as blocking links

• kit: Dedupe layers that are both auto-scanned and explicitly extended

• nuxt: Don't apply scroll behaviour after a subsequent nav

• vite: Ensure server sourcemap-preserver plugin actually runs

• vite: Preserve css suffix when extracting ssr inline styles

• nuxt: Watch external component directories in development

• nuxt: Don't exclude client entry module from style extraction

• nuxt: Amend cleanup command in NUXT_B7014 error message

• nuxt: Only pull in vue-router when there are island pages

• vite: Suppress external warnings for internal vite-node paths

• nuxt: Use scope-aware oxc parser for auto-imports

• nuxt: Sync layout meta during middleware on SSR

• nitro: Add alias for h3 that pins it to the version nuxt depends on

• nuxt: Preserve query params in cached payload extraction

• nuxt: Mirror runtime route tree in generated typed-router types

• nuxt: Warn when an imports preset from cannot be resolved

• kit: Avoid mutating layer configs when resolving options

• nuxt: Convert inline route rules exactly or drop with a warning

• nitro,nuxt,vite: Dedupe and normalise global css links in dev

• vite: Register template HMR plugin on dev servers

• nuxt: Remove dev error overlay when error is cleared

• rspack,webpack: Resolve bundled postcss defaults from builder

• schema: Normalise slashes in app.buildAssetsDir

• nitro: Bound island props and v-for to prevent unauthenticated DoS

• nitro: Confine runtime payload cache to prerendering

• nuxt: Case-fold route rule keys to match folded lookups

• nitro: Require loopback peer for chrome devtools workspace endpoint

• nuxt: Reject reserved template island prop under runtime compiler

• nuxt: Reject top-level as prop for islands