JavaScript is required for this site to function.
About Leópold Kristjánsson

How to set up a custom sitemap.xml for your Nuxt website

  • Nuxt
  • SEO
  • Technical SEO

Although Nuxt does have the off-the-shelf Nuxt Sitemap module to create sitemap.xml files, I often tend to custom build it to get the flexibility I need and to reduce dependencies. All you need is a single server/routes/sitemap.xml.ts endpoint.

Why make the sitemap yourself?

The main reasons for me are:

  • the flexibility you get
  • not having to read through any documentation and learn a specific API
  • not having to install a dependency (I always feel like that's a small victory)

Once you've set this up for the first time, repeating it becomes very straightforward. The template stays the same and can be used in all your Nuxt projects (and technically in non-Nuxt projects as well with small modifications). The only part that needs your attention is the data fetching and filtering, and that can be as custom as you want. It becomes very easy to reason about the logic since it is just a normal TypeScript file.

A sitemap.xml file for leopold.is displayed as an XML document in a web browser.
An example sitemap.xml file as displayed in Chrome.

The route and template

In Nuxt, you can create a server route at server/routes/sitemap.xml.ts. Because the filename includes .xml, Nuxt will serve it at /sitemap.xml. You still need to set the Content-Type header correctly so clients, including browsers and search engine crawlers, interpret the response as XML.

From there, it is just server-side TypeScript. Fetch your pages, filter them, map them into sitemap entries, escape the XML values, and return the response with a text/xml content type.

The example below produces a simple sitemap.xml file that combines a few predefined routes with a list of dynamic routes fetched from an API, so the list stays up to date. In the example the dynamic routes include lastmod (let's imagine the API provides a reliable last-updated date) but it is left out for the predefined routes because we do not have it there, and an inaccurate date is less useful than no date at all. This is only an example, of course; this is exactly the part that will look different for every website.

server/routes/sitemap.xml.ts
TypeScript
// Each sitemap entry requires a URL and can optionally include
// lastmod, changefreq and priority.
// This example skips changefreq and priority
// since we know it is mostly ignored.
type SitemapUrl = {
  loc: string
  lastmod?: string
}

const baseUrl = 'https://example.com'

// We need to escape reserved XML characters so values remain valid inside the sitemap.
const escapeXml = (value: string) =>
  value
    .replaceAll('&', '&')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
    .replaceAll('"', '&quot;')
    .replaceAll("'", '&apos;')

// A function to convert a sitemap URL into its XML representation.
const getUrlXml = (url: SitemapUrl) => {
  const lastmod = url.lastmod
    ? `\n    <lastmod>${escapeXml(url.lastmod)}</lastmod>`
    : ''

  return `  <url>
    <loc>${escapeXml(url.loc)}</loc>${lastmod}
  </url>`
}

// In this example we are building the sitemap from a few predefined
// URLs as well as an unknown number of blog articles fetched from an API.
export default defineEventHandler(async () => {
  const staticUrls: SitemapUrl[] = [
    { loc: `${baseUrl}/` },
    { loc: `${baseUrl}/blog/` },
    { loc: `${baseUrl}/contact/` },
  ]

  // Here we fetch and filter blog articles from a database.
  // Replace this with your CMS, database, file system, or API call.
  const articles = await getPublishedArticles()

  const articleUrls = articles
    .filter((article) => article.isPublished)
    .filter((article) => !article.noindex)
    .filter((article) => article.locale === 'en')
    .map((article) => ({
      loc: `${baseUrl}/blog/${article.slug}/`,
      lastmod: article.updatedAt,
    }))

  // Here we combine the static and the dynamic URLs that we have.
  const urls = [...staticUrls, ...articleUrls]

  // Create the XML document. The declaration sets XML 1.0 and UTF-8,
  // while xmlns identifies the standard sitemap protocol used by <urlset>.
  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urls.map(getUrlXml).join('\n')}
</urlset>`

  // Return the XML with the correct content type so clients interpret it as XML.
  return new Response(xml, {
    headers: {
      'content-type': 'text/xml; charset=UTF-8',
    },
  })
})

The example above is simple, and in a real application you might extract some of the utility functions, the data fetching logic might take up more space and so on.

But I hope the idea is clear: it is rather simple to set this up.

Cache the sitemap endpoint

A sitemap.xml route often has to pull together data from multiple sources, which can be a bit heavy. Imagine you have pages for products, news, authors, job listings, legal pages, or whatever else. For most sites, the list of pages does not change frequently enough to justify fetching this fresh on each crawler request.

In Nuxt, I would usually start with route rules in nuxt.config.ts. A sitemap can be cached for a short, predictable window, then regenerated when the cached response gets stale.

nuxt.config.ts
TypeScript
export default defineNuxtConfig({
  routeRules: {
    '/sitemap.xml': {
      swr: 60 * 60,
    },
  },
})

This example uses stale-while-revalidate for one hour. The first request after the cache gets stale can refresh the sitemap while later requests keep getting a cached response.

The exact caching behavior can depend on a few things, for example where your Nuxt app/website is hosted. Depending on the platform, route rules may be translated into platform-specific caching behavior. If the host does not apply those rules the way you expect, the fallback can be to set explicit cache-control headers from the endpoint, for example with an s-maxage value for shared CDN caches.

Summary and further reading

To set up a custom sitemap in Nuxt, create a server/routes/sitemap.xml.ts endpoint that gathers your public URLs, converts them to XML, and returns the result with the correct Content-Type. Add the fetching and filtering your project needs, and cache the endpoint so that work is not repeated for every crawler request.

Further reading

Continue reading