Nuxt Sitemap v9.0.0

Introduction

Nuxt Sitemap v9 moves the module to Nuxt 4.6 and Nuxt 5. Server code now uses the portable nuxt/server APIs.

v9 ships in Nuxt SEO v6. If you use @nuxtjs/seo, follow the Nuxt SEO v5 to v6 migration guide.

Read the breaking changes below, then follow the upgrade steps.

⚠️ Breaking Changes

Nuxt 4.6 and Node 22

v9 requires Nuxt ^4.6.0 || ^5.0.0. Nuxt 3 and Nuxt 4 releases before 4.6 are not supported. The Node engine range is ^22.22.3 || ^24.15.0 || >=26.0.0. (#687)

With future.compatibilityVersion: 5, use 9.0.3 or later. Earlier v9 releases fail the build with defineAppConfig is not defined when app.config.ts calls defineAppConfig(). See Troubleshooting.

Server events use `RequestEvent`

Sitemap Nitro hooks receive a RequestEvent from nuxt/server. This covers sitemap:input, sitemap:resolved, sitemap:index-resolved, sitemap:sitemaps-resolved, sitemap:output and sitemap:sources. (#687)

The RequestEvent type has no event.node property. Read headers from the web Request:

 nitroApp.hooks.hook('sitemap:sources', async (ctx) => {
-  const authHeader = ctx.event.node.req.headers.authorization
+  const authHeader = ctx.event.req.headers.get('authorization')
 })

Import server helpers from `#sitemap/server`

defineSitemapEventHandler() and asSitemapUrl() have a typed public import path. Server auto imports still resolve both names.

-import { defineSitemapEventHandler } from '#imports'
+import { defineSitemapEventHandler } from '#sitemap/server'

defineSitemapEventHandler() now wraps defineEventHandler() from nuxt/server. Its event is a RequestEvent. Use request utilities from nuxt/server, such as getQuery().

The event is also typed as the server builder's own H3Event, so h3 helpers and site utilities typed against H3Event still accept it. event.req is now the web Request:

 export default defineSitemapEventHandler((event) => {
-  const locale = event.req.headers['accept-language']
+  const locale = event.req.headers.get('accept-language')
   return [{ loc: `/${locale}/about` }]
 })

Nuxt Robots v7 and Nuxt Site Config v5

v9 loads Nuxt Site Config v5 through Nuxt module dependencies. (#695)

If you use Nuxt Robots, upgrade it to v7. The sitemap reads robots rules from #robots/server. The module no longer detects the legacy nuxt-simple-robots package. (#687)

Nuxt Content v2 removed

v9 supports Nuxt Content v3 only. The strictNuxtContentPaths option and the @nuxt/content@v2:urls app source are removed. (#698)

If you use Nuxt Content v2, upgrade to Nuxt Content v3. Then add defineSitemapSchema() to each page collection. See Nuxt Content.

Zod 4 for content schemas

The optional zod peer is now ^4.6.5. If you use defineSitemapSchema(), install Zod 4.6.5 or a later 4.x release. The Zod 3 mismatch warning is removed. (#687)

DevTools needs `nuxtseo-devtools-host`

The DevTools panel moved to an optional package. Install it as a dev dependency:

pnpm add -D nuxtseo-devtools-host

Restart the dev server after you install it. You do not add the package to modules. Without it, the Sitemap tab shows an install button.

🚀 New Features

Typed `#sitemap/server` imports

Server helpers and types now have one typed import path. The alias works on Nuxt 4.6 and Nuxt 5. (#687)

server/api/__sitemap__/urls.ts

import type { SitemapUrlInput } from '#sitemap/server'
import { defineSitemapEventHandler } from '#sitemap/server'
import { getQuery } from 'nuxt/server'

export default defineSitemapEventHandler((event) => {
  const { lang } = getQuery(event)
  return [{ loc: `/${lang}/about` }] satisfies SitemapUrlInput[]
})

🐛 Bug Fixes

Prerendered dynamic pages with definePageMeta({ sitemap: false }) are now excluded. (#691)
Page exclusions use the app router matcher. They respect sensitive, strict and end, nested routes and page aliases. (#692)
Nuxt 5 development no longer blocks on page resolution. Sitemap sources reload when pages change. (#688)
Local source requests keep authentication headers and query options during HTTP rendering and static generation. (#687)
Robots restrictions on a staging site no longer empty the sitemap. Explicit global and route noindex headers still exclude URLs. (#687)

⚡ Performance

When experimentalStreaming and experimentalCompression are off, the build removes their code. In one measured app, total server JavaScript fell from 2,054,112 to 2,046,716 bytes. (#690)
pathe and pkg-types are no longer direct dependencies. (#687)

Upgrading

Upgrade to Nuxt 4.6 or Nuxt 5. Use Node 22.22.3+, 24.15.0+, or 26+.
If you use @nuxtjs/seo, upgrade it to v6. Nuxt SEO v6 includes Sitemap v9.
Otherwise, install @nuxtjs/sitemap v9. If you use @nuxtjs/robots, upgrade it to v7.
In sitemap hooks and handlers, replace event.node.req with event.req.
Import defineSitemapEventHandler() and asSitemapUrl() from #sitemap/server.
If you use Nuxt Content v2, upgrade to Nuxt Content v3. Remove strictNuxtContentPaths.
If you use the DevTools Sitemap tab, run pnpm add -D nuxtseo-devtools-host.