nuxt

👀 Highlights

I'm pretty excited about this release - we've ported some features we had planned for Nuxt v4 back to v3, as well as a raft of bug fixes and performance improvements - as usual.

Here are a few of things I'm most excited about.

🏘️ Route Groups

We now support naming directories with parentheses/brackets to organise your routes without affecting the path.

For example:

-| pages/
---| index.vue
---| (marketing)/
-----| about.vue
-----| contact.vue

This will produce /, /about and /contact pages in your app. The marketing group is ignored for purposes of your URL structure.

Read more in the original PR.

🏝️ Islands and Head Metadata

It's now possible for server component islands to manipulate the head, such as by adding SEO metadata when rendering.

Read more in #27987.

🪝 Custom Prefetch Triggers

We now support custom prefetch triggers for NuxtLink (#27846).

For example:

<template>
  <div>
    <NuxtLink prefetch-on="interaction">
      This will prefetch when hovered or when it gains focus
    </NuxtLink>
    <!-- note that you probably don't want both enabled! -->
    <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
      This will prefetch when hovered/focus - or when it becomes visible
    </NuxtLink>
  </div>
</template>

It's also possible to enable/disable these globally for your app and override them per link.

For example:

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: true,
        prefetchOn: { visibility: false, interaction: true }
      }
    }
  }
})

🗺️ Better Server Source Maps

When running with node --enable-source-maps, you may have noticed that the source maps for the Vue files in your server build pointed to the Vite build output (something like .nuxt/dist/server/_nuxt/index-O15BBwZ3.js).

Now, even after your Nitro build, your server source maps will reference your original source files (#28521).

Note that one of the easiest ways of improving your build performance is to turn off source maps if you aren't using them, which you can do easily in your nuxt.config:

export default defineNuxtConfig({
  sourcemap: {
    server: false,
    client: true,
  },
})

🎁 New Features for Module Authors

In the run-up to Nuxt v4, we're working on adding some key functionality for module authors, including a new isNuxtMajorVersion utility where required (#27579) and better inferred typing for merged module options using the new defineNuxtModule().with() method (#27520).

✨ Improved Dev Warnings

We no longer warn when using data fetching composables in middleware (#28604) and we warn when user components' names begin with Lazy (#27838).

🚨 Vue TypeScript Changes

For a while, in the Vue ecosystem, we've been augmenting @vue/runtime-core to add custom properties and more to vue. However, this inadvertently breaks the types for projects that augment vue - which is now the officially recommended in the docs way to augment these interfaces (for example, ComponentCustomProperties, GlobalComponents and so on).

This means all libraries must update their code (or it will break the types of libraries that augment vue instead).

We've updated our types in Nuxt along these lines but you may experience issues with the latest vue-router when used with libraries which haven't yet done so.

Please create an issue with a reproduction - I'll happily help create a PR to resolve in the upstream library in question. Or you may be able to work around the issue by creating a declarations.d.ts in the root of your project with the following code (credit):

import type {
  ComponentCustomOptions as _ComponentCustomOptions,
  ComponentCustomProperties as _ComponentCustomProperties,
} from 'vue';

declare module '@vue/runtime-core' {
  interface ComponentCustomProperties extends _ComponentCustomProperties {}
  interface ComponentCustomOptions extends _ComponentCustomOptions {}
}

✅ Upgrading

As usual, our recommendation for upgrading is to run:

npx nuxi@latest upgrade --force

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

👉 Changelog

compare changes

🚀 Enhancements

• nuxt: Await custom routes function in router.options (#27644)
• kit: Add new isNuxtMajorVersion compatibility util (#27579)
• kit,schema: Add .with for better module options types (#27520)
• nuxt: Warn when user components' names begin with Lazy (#27838)
• nuxt: Allow specifying app id when creating a nuxt app (#28392)
• nuxt: Custom enable/disable hooks for usePreviewMode (#28371)
• kit: Add prepend option to addRouteMiddleware (#28496)
• nuxt: Allow organising pages within route groups (#28276)
• vite: Preserve vite sourcemaps for nitro build (#28521)
• nuxt: Allow defining triggers for prefetching links (#27846)
• nuxt: Namespace __NUXT__ when using multi-app (#27263)
• nuxt: Allow server islands to manipulate head (#27987)

🔥 Performance

• nuxt: Call cookie decode function only for named cookie (#28215)
• nuxt: Avoid making client-only component setup async (#28334)
• nuxt: Avoid multiple calls to getCachedData (#28472)

🩹 Fixes

• nuxt: Don't warn for definePageMeta in client-only pages (#28246)
• kit: Include module dist/runtime/ in tsconfig includes (#28237)
• schema: Support absolute/relative paths for assetsDir (59f0099f4)
• schema: Do not override user serverDir (#28249)
• schema: Use new options syntax for vite-plugin-vue (#28307)
• schema: Export new module return types (c0ad8db93)
• kit: Add missing type import (1a60b4541)
• vite,webpack: Handle local postcss plugins (#28481)
• nuxt: Handle scroll-padding-top: auto in scrollBehavior (#28320)
• nuxt: Ensure runtimeConfig.public is reactive on client (#28443)
• nuxt: Update renamed stub composables from nuxt/scripts (#28449)
• nuxt: Augment @vue/runtime-core and @vue/runtime-dom (#28446)
• nuxt: Scan jsx pages for page metadata (#28479)
• nuxt: Handle plugin type extensions more correctly (#28480)
• vite: Respect baseURL for public assets in dev ()

📖 Documentation

• Fix issue in cookie passing example (#28223)
• Fix note in layers usage chapter (#28236)
• Fix spaces (#28233)
• Add vue lang to sample code (#28247)
• Use splitSetCookieString from cookie-es (29f95ae0d)
• Use headers.getSetCookie (45c6df9a4)
• Fix codemod command typos (#28279)
• bunx -> bun x (#28277)
• Add missing comma to example (#28300)
• Add language to example schema codeblock (#28294)
• Update link to RuntimeNuxtHooks (#28336)
• Update links to social media (cd5195047)
• Setup host property and usage example (#28331)
• Fix TypeScript errors for examples (#28403)
• Improve readability of link to mdn (#28327)
• Use ts for create-error example (#28411)
• Alias links in jsdoc @see blocks (#28270)
• Link to vue test utils docs for mountSuspended (#28463)
• Remove vue-tsc major version constraint (#28484)

🏡 Chore

• schema: Fix typo (#28377)
• nuxt: Use router code reference permalink (#28356)
• nuxt: Remove unnecessary await (#28407)
• Upgrade vue in a separate pr (#28414)
• Update docs typecheck command (49de5f731)
• Lint (cab9e5c35)
• Fix some typos in comments (#28501)

✅ Tests

• Disable pageTransition in client-only page (#27839)
• Ignore SharedComponent in server head (510f3e28f)
• Update bundle size (3ecb95a7c)

🤖 CI

• Add reproduire-sur-stackblitz workflow (#28531)

❤️ Contributors

• Daniel Roe (@danielroe)
• Julien Huang (@huang-julien)
• Maxime Pauvert (@maximepvrt)
• felix-dolderer (@felix-dolderer)
• Nicolas Payot (@nicolaspayot)
• Kewin Szlezingier (@kewinzaq1)
• Vasily Kuzin (@ExEr7um)
• xjccc (@xjccc)
• Martin André (@Martichou)
• Mike Laumann Bellika (@MikeBellika)
• Typed SIGTERM (@typed-sigterm)
• Horu (@HigherOrderLogic)
• Son Tran (@trandaison)
• rubyisrust (@rubyisrust)
• Matej Černý (@CernyMatej)
• Riley Ho (@rileychh)
• Adam DeHaven (@adamdehaven)
• Potter (@yxw007)
• Martin Masevski (@Archetipo95)
• BoogieBen. (@boogie-ben)
• Tobias Diez (@tobiasdiez)
• Michael Brevard (@GalacticHypernova)
• Damian Głowala (@DamianGlowala)
• Lucie (@lihbr)
• Yasser Lahbibi (@yassilah)
• Sébastien Chopin (@atinux)
• @beer (@iiio2)
• AuroraTea (@AuroraTea)
• Bobbie Goede (@BobbieGoede)
• Alexander Lichter (@manniL)
• nuxt-studio[bot] (@nuxt-studio[bot])
• Vaci (@vacijj)
• FELIPE COSTA DE OLIVEIRA (@FelipeO16)
• 一纸忘忧 (@ikxin)
• Meo (@miaobuao)
• Mohab Sameh (@mohab-sameh)
• Quentin Macq (@quentinmcq)
• Johan Krijt (@johankrijt)