@nuxtjs/sitemap 2.0.0

v2.0.0

on Node.js NPM

This module has been mostly rewritten from scratch solving major outstanding issues in preparation for Nuxt SEO Kit v2 release.

🚀 Features

• SSR Support

Previously only a preview of the sitemap was shown when SSR. Now full SSR is supported.

• Styled XML

A new XML stylesheet is used to style the sitemap to make it easier to read and debug.

• Prerendering Image Inferances

When prerendering it will automatically detect and add <image:image> entries from the content of your <main> tag.

• Multiple sitemaps support

You can now generate multiple sitemaps using the sitemaps option.

Automatic chunking: true

This will automatically chunk your sitemap into multiple-sitemaps for every 1000 URLs, using the 0-sitemap.xml, 1-sitemap.xml naming convention.

You should avoid using this if you have less than 1000 URLs.

export default defineNuxtConfig({
  sitemap: {
    // automatically chunk into multiple sitemaps
    sitemaps: true,
  },
})

Manual chunking

You can manually chunk your sitemap into multiple sitemaps by providing filter options.

export default defineNuxtConfig({
  sitemap: {
    // manually chunk into multiple sitemaps
    sitemaps: {
      posts: {
        include: [
          '/blog/**',
        ],
        // example: give blog posts slightly higher priority (this is optional)
        defaults: { priority: 0.7 },
      },
      pages: {
        exclude: [
          '/blog/**',
        ]
      },
    },
  },
})

For each sitemaps entry, you can provide the following options:

• include - Array of glob patterns to include in the sitemap

• exclude - Array of glob patterns to exclude from the sitemap

• defaults - Sitemap default values such as lastmod, changefreq, priority`

• urls - Array of static URLs to include in the sitemap. You should avoid using this option if you have a lot of URLs, instead see below Handling dynamic URLs

• Auto lastmod

By default, the sitemap module will automatically detect the lastmod date for each URL.

This is done by looking at the ctime of the page file associated with a route.

If a route can't be associated with a page file then the current date will be used.

You can disable this behaviour by setting autoLastmod: false.

export default defineNuxtConfig({
  sitemap: {
    autoLastmod: false,
  },
})

• Runtime dynamic URL support

You can now create your own api endpoint that returns the list of all dynamic routes.

To do so, create the file server/api/_sitemap-urls.ts.

export default cachedEventHandler(async e => {
  const [
    posts,
    pages,
    products
  ] = await Promise.all([
    $fetch('/api/posts'),
    $fetch('/api/pages'),
    $fetch('/api/products')
  ])
  return [...posts, ...pages, ...products].map(p => { loc: p.url, lastmod: p.updatedAt })
}, {
  name: 'sitemap-dynamic-urls',
  maxAge: 60 * 10 // cache URLs for 10 minutes
})

This API endpoint will automatically be called by the sitemap module to fetch the list of dynamic URLs whenever a sitemap is generated.

While not required, it's recommended to use the cacheEventHandler and set an appropriate maxAge, 10 minutes is a good default.

• New hooks

sitemap:prerender

This nuxt hook allows you to modify the sitemap(s) urls when they're prerendered.

Note: For dynamic runtime sitemaps this hook won't do anything.

export default defineNuxtConfig({
  hooks: {
    'sitemap:prerender': (ctx) => {
      // single sitemap example - just add the url directly
      ctx.urls.push({
        loc: '/my-secret-url',
        changefreq: 'daily',
        priority: 0.8,
      })
      // multi sitemap example - filter for a sitemap name
      if (ctx.sitemapName === 'posts') {
        ctx.urls.push({
          loc: '/posts/my-post',
          changefreq: 'daily',
          priority: 0.8,
        })
      }
    },
  },
})

sitemap:sitemap-xml

This nitro hook allows you to modify the sitemap.xml as runtime before it is sent to the client.

Note: For pre-rendered site maps this hook won't do anything.

import { defineNitroPlugin } from 'nitropack/runtime/plugin'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:sitemap-xml', async (ctx) => {
    // single sitemap example - just add the url directly
    ctx.urls.push({
      loc: '/my-secret-url',
      changefreq: 'daily',
      priority: 0.8,
    })
    // multi sitemap example - filter for a sitemap name
    if (ctx.sitemapName === 'posts') {
      ctx.urls.push({
        loc: '/posts/my-post',
        changefreq: 'daily',
        priority: 0.8,
      })
    }
  })
})

⚡ Performance improvements

• dropped sitemap dependency

⚠️ Deprecations / Breaking Changes

• requires Nuxt ^3.3.1

• hostname has been deprecated in favour of using siteUrl. If you were using the hostname key explicitly over the runtime config then you should change it to siteUrl. Using runtime config is recommended though.

export default defineNuxtConfig({
  sitemap: {
-    hostname: 'https://example.com',
+    siteUrl: 'https://example.com',
  }
})

Recommended

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      // can be set with environment variables
      siteUrl: process.env.NUXT_PUBLIC_SITE_URL || 'https://example.com',
    }
  },
})

• devPreview has been removed.

It was initially introduced to avoid the overhead of fetching URLs in development when they weren't needed. This can be resolved by moving dynamic URLs to /server/api/_sitemap-urls.ts

Additionally, the /sitemap.preview.xml is no longer available.

export default defineNuxtConfig({
  sitemap: {
-    devPreview: false,
  }
})

• The sitemap:generate hook has been deprecated and the sitemap key no longer exists.

If you're intending on pre-rendering your sitemap then you can use the new sitemap:prerender hook.