Data Sources

Where do sitemap URLs come from?

After installing the module, you may wonder: where do the URLs in your sitemap come from?

Every URL belongs to a source. There are two types:

• Application Sources - Automatically discovered from your Nuxt app
• User Sources - Manually provided by you

For most sites, application sources handle everything automatically. You only need user sources when you have dynamic routes from a CMS or database.

Application Sources

Application sources are automatically generated from your Nuxt application. They provide convenience by automatically discovering URLs from your app's structure, but can be disabled if they don't match your needs.

• nuxt:pages - Statically analyzed pages of your application (including definePageMeta sitemap config)
• nuxt:prerender - URLs that were prerendered
• nuxt:route-rules - URLs from your route rules
• @nuxtjs/i18n:pages - When using the pages config with Nuxt I18n. See Nuxt I18n for more details.
• nuxt-i18n-micro:pages - When using the pages config with Nuxt I18n Micro. See Nuxt I18n for more details.
• @nuxt/content@v3:urls - When using Nuxt Content v3. See Nuxt Content for more details.

Disabling application sources. You can disable application sources individually or all at once using the excludeAppSources config option.

export default defineNuxtConfig({
  sitemap: {
    // exclude all app sources
    excludeAppSources: true,
  }
})

export default defineNuxtConfig({
  sitemap: {
    // exclude static pages
    excludeAppSources: ['nuxt:pages'],
  }
})

User Sources

User sources allow you to manually configure where your sitemap URLs come from. These are especially useful for dynamic routes that aren't using prerendering discovery.

You have several options for providing user sources:

1. Build-time Sources with urls Function

For sitemap data that only needs to be updated at build time, the urls function is the simplest solution. This function runs once during sitemap generation.

It should return an array of path strings or URL objects.

export default defineNuxtConfig({
  sitemap: {
    urls: ['/about', '/contact', '/products/special-offer']
  }
})

export default defineNuxtConfig({
  sitemap: {
    urls: async () => {
      const response = await fetch('https://api.example.com/posts')
      const posts = await response.json()
      return posts.map(post => ({
        loc: `/blog/${post.slug}`,
        lastmod: post.updated_at,
      }))
    }
  }
})

2. Runtime Sources with sources Array

For sitemap data that must always be up-to-date at runtime, use the sources array. Each source is a URL that gets fetched and should return either:

• JSON array of sitemap URL entries
• XML sitemap document

export default defineNuxtConfig({
  sitemap: {
    sources: [
      // create our own API endpoints
      '/api/__sitemap__/urls',
      // use a static remote file
      'https://cdn.example.com/my-urls.json',
      // hit a remote API with credentials
      ['https://api.example.com/pages/urls', { headers: { Authorization: 'Bearer <token>' } }]
    ]
  }
})

export default defineNuxtConfig({
  sitemap: {
    sitemaps: {
      foo: {
        sources: [
          '/api/__sitemap__/urls/foo',
        ]
      },
      bar: {
        sources: [
          '/api/__sitemap__/urls/bar',
        ]
      }
    }
  }
})

The module caches the resolved sitemap in production, so sources are not fetched on every crawler request. Add endpoint caching only when a source is slow, rate limited, or metered. See Which handler should I use?.

Learn more about working with dynamic data in the Dynamic URLs guide.

3. Dynamic Sources Using Nitro Hooks. For advanced use cases like forwarding authentication headers or adding sources based on request context, see the Nitro Hooks documentation.