README

Sitemap Module

Automatically generate or serve dynamic sitemap.xml for Nuxt.js projects!

Features

Module based on the awesome sitemap.js package ❤️
Create sitemap or sitemap index
Automatically add the static routes to each sitemap
Support i18n routes from nuxt-i18n (latest version)
Works with all modes (SSR, SPA, generate)
For Nuxt 2.x and higher

Install
Setup
Usage
Sitemap Options
Sitemap Index Options
Routes Declaration
Hooks

Installation

npm install @nuxtjs/sitemap

yarn add @nuxtjs/sitemap

Setup

Add @nuxtjs/sitemap to the modules section of your nuxt.config.js file:

{
  modules: [
    '@nuxtjs/sitemap'
  ],
}

notice:
If you use other modules (eg. nuxt-i18n), always declare the sitemap module at end of array
eg. modules: ['nuxt-i18n', '@nuxtjs/sitemap']

Configuration

Add a custom configuration with the sitemap property:

// nuxt.config.js

{
  modules: [
    '@nuxtjs/sitemap'
  ],
  sitemap: {
    // options
  },
}

The module option parameter can be:

`Object`

A single item of sitemap or sitemap index:

{
  sitemap: {
    // ...
  },
}

`Array`

A list of sitemap or sitemap index items:

{
  sitemap: [
    {
      // ...
    },
    {
      // ...
    },
  ],
}

`Function`

A function that returns a valid sitemap configuration:

{
  sitemap: function () {
    return {
      // ...
    }
  },
}

`Boolean`

You can disable the sitemap module with a boolean value at false:

{
  sitemap: false
}

Usage

Setup a Sitemap

By default, the sitemap is setup to the following path: /sitemap.xml
All static routes (eg. /pages/about.vue) are automatically add to the sitemap, but you can exclude each of them with the exclude property.
For dynamic routes (eg. /pages/_id.vue), you have to declare them with the routes property. This option can be an array or a function. In addition, the routes defined in generate.routes will be automatically used for the sitemap.

// nuxt.config.js

{
  sitemap: {
    hostname: 'https://example.com',
    gzip: true,
    exclude: [
      '/secret',
      '/admin/**'
    ],
    routes: [
      '/page/1',
      '/page/2',
      {
        url: '/page/3',
        changefreq: 'daily',
        priority: 1,
        lastmod: '2017-06-30T13:30:00.000Z'
      }
    ]
  }
}

Setup a Sitemap Index

To declare a sitemap index and its linked sitemaps, use the sitemaps property.
By default, the sitemap index is setup to the following path: /sitemapindex.xml
Each item of the sitemaps array can be setup with its own sitemap options.

// nuxt.config.js

{
  sitemap: {
    hostname: 'https://example.com',
    lastmod: '2017-06-30',
    sitemaps: [
      {
        path: '/sitemap-foo.xml',
        routes: ['foo/1', 'foo/2'],
        gzip: true
      }, {
        path: '/folder/sitemap-bar.xml',
        routes: ['bar/1', 'bar/2'],
        exclude: ['/**']
      }
    ]
  }
}

Setup a list of sitemaps

To declare a list of sitemaps, use an array to setup each sitemap with its own configuration.
You can combine sitemap and sitemap index configurations.

// nuxt.config.js

{
  sitemap: [
    {
      path: '/sitemap-products.xml',
      routes: [
        // array of URL
      ]
    }, {
      path: '/sitemap-news.xml',
      routes: () => // promise or function
    }, {
      path: '/sitemapindex.xml',
      sitemaps: [{
        // array of Sitemap configuration
      }]
    }
  }
}

Sitemap Options

`routes` (optional) - array | function

Default: [] or generate.routes value from your nuxt.config.js

The routes parameter follows the same way than the generate configuration.

See as well the routes declaration examples below.

`path` (optional) - string

Default: /sitemap.xml

The URL path of the generated sitemap.

`hostname` (optional) - string

Default:
1. sitemap.hostname value from your nuxt.config.js
2. build.publicPath value from your nuxt.config.js (⚠️ deprecated)
3. os.hostname() in generate or spa mode, or dynamically based on request URL (headers.host) in ssr mode

This value is mandatory for generation sitemap file, and you should explicitly provide it in generate or spa mode.

⚠️ The usage of build.publicPath as default value is deprecated and will be removed on release v3.0.
To disable it on the current release, set a falsy value (eg. hostname: false).

`cacheTime` (optional) - number

Default: 1000 * 60 * 15 (15 Minutes)

Defines how frequently sitemap routes should be updated (value in milliseconds).
Setting a negative value will disable the cache.

Please note that after each invalidation, routes will be evaluated again (see routes declaration section).

This option is only available in ssr mode.

`etag` (optional) - object

Default: render.etag value from your nuxt.config.js

Enable the etag cache header on sitemap (see etag docs for possible options).

To disable etag for sitemap set etag: false

This option is only available in ssr mode.

`exclude` (optional) - string array

Default: []

The exclude parameter is an array of glob patterns to exclude static routes from the generated sitemap.

`filter` (optional) - function

Default: undefined

If the filter option is set as a function, all routes will be filtered through it.

This option is useful to customize or extend the features of the module, before the sitemap generation.

Examples:

// nuxt.config.js

// Filter routes by language
{
  sitemap: {
    filter ({ routes, options }) {
      if (options.hostname === 'example.com') {
        return routes.filter(route => route.locale === 'en')
      }
      return routes.filter(route => route.locale === 'fr')
    }
  }
}

// Add a trailing slash to each route
{
  sitemap: {
    filter ({ routes }) {
      return routes.map(route => {
        route.url = `${route.url}/`
        return route
      })
    }
  }
}

`gzip` (optional) - boolean

Default: false

Enable the creation of the .xml.gz sitemap compressed with gzip.

`xmlNs` (optional) - string

Default: undefined

Set the XML namespaces by override all default xmlns attributes in <urlset> element.

// nuxt.config.js

{
  sitemap: {
    xmlNs: 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"'
  }
}

`xslUrl` (optional) - string

Default: undefined

The URL path of the XSL file to style the sitemap.

`trailingSlash` (optional) - boolean

Default: false

Add a trailing slash to each route URL (eg. /page/1 => /page/1/)

notice: To avoid duplicate content detection from crawlers, you have to configure an HTTP 301 redirect between the 2 URLs (see redirect-module or nuxt-trailingslash-module).

`i18n` (optional) - string | object

Default: undefined

Configure the support of localized routes from nuxt-i18n module.

If the i18n option is configured, the sitemap module will automatically add the default locale URL of each page in a <loc> element, with child <xhtml:link> entries listing every language/locale variant of the page including itself (see Google sitemap guidelines).

Example:

// nuxt.config.js

{
  modules: [
    'nuxt-i18n',
    '@nuxtjs/sitemap'
  ],
  i18n: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en'
  },
  sitemap: {
    hostname: 'https://example.com',
    // shortcut notation (basic)
    i18n: true,
    // nuxt-i18n notation (advanced)
    i18n: {
      locales: ['en', 'es', 'fr'],
      routesNameSeparator: '___'
    }
  }
}

  <url>
    <loc>https://example.com/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/es/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/fr/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/"/>
  </url>

`defaults` (optional) - object

Default: {}

The defaults parameter set the default options for all routes.

// nuxt.config.js

{
  sitemap: {
    defaults: {
      changefreq: 'daily',
      priority: 1,
      lastmod: new Date()
    }
  }
}

See available options: https://github.com/ekalinin/sitemap.js/blob/4.1.1/README.md#sitemap-item-options

Sitemap Index Options

`path` (optional) - string

Default: /sitemapindex.xml

The URL path of the generated sitemap index.

`hostname` (optional) - string

Set the hostname value to each sitemap linked to its sitemap index.

`sitemaps` - array of object

Default: []

Array of sitemap configuration linked to the sitemap index.

// nuxt.config.js

{
  sitemap: {
    path: '/sitemapindex.xml',
    hostname: 'https://example.com',
    sitemaps: [
      {
        path: '/sitemap-foo.xml',
        // ...
      }, {
        path: '/folder/sitemap-bar.xml',
        // ...
      }
    ]
  }
}

<!-- generated sitemapindex.xml -->

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-foo.xml</loc>
  </sitemap>
  <sitemap>
    <loc>https://example.com/folder/sitemap-bar.xml</loc>
  </sitemap>
</sitemapindex>

See more examples above.

`lastmod` (optional) - string

Set the lastmod value to each sitemap linked to its sitemap index.

In addition, the lastmod can be defined for each linked sitemap.

// nuxt.config.js

{
  sitemap: {
    lastmod: "2020-01-01",
    sitemaps: [
      {
        path: '/sitemap-foo.xml',
        lastmod: "2020-01-02"
      }, {
        path: '/sitemap-bar.xml'
      }
    ]
  }
}

`etag` (optional) - object

Default: render.etag value from your nuxt.config.js

Enable the etag cache header on sitemap index (See etag docs for possible options).

To disable etag for sitemap index set etag: false

This option is only available in ssr mode.

`gzip` (optional) - boolean

Default: false

Enable the creation of the .xml.gz sitemap index compressed with gzip.

`xmlNs` (optional) - string

Default: undefined

Set the XML namespaces by override all default xmlns attributes in <sitemapindex> element.

// nuxt.config.js

{
  sitemap: {
    xmlNs: 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"',
    sitemaps: [...]
  }
}

`xslUrl` (optional) - string

Default: undefined

The URL path of the XSL file to style the sitemap index.

Routes Declaration

By default, the dynamic routes are ignored by the sitemap module.
Nuxt cannot automatically provide this type of complex routes.

Example:

-| pages/
---| index.vue  --> static route
---| about.vue  --> static route
---| users/
-----| _id.vue  --> dynamic route

If you want the module to add any route with dynamic parameters, you have to set an array of dynamic routes.

eg. add routes for /users/:id in the configuration:

From a static list

// nuxt.config.js

{
  sitemap: {
    routes: ['/users/1', '/users/2', '/users/3']
  }
}

From a function which returns a Promise

// nuxt.config.js

const axios = require('axios')

{
  sitemap: {
    routes: async () => {
      const { data } = await axios.get('https://jsonplaceholder.typicode.com/users')
      return data.map((user) => `/users/${user.username}`)
    }
  }
}

Hooks

Hooks are listeners to Nuxt events. Learn more

You can register hooks on certain life cycle events.

Hook	Arguments	When
sitemap:generate:before	(nuxt, sitemapOptions)	Hook on before site generation
sitemap:generate:done	(nuxt)	Hook on sitemap generation finished

License

MIT License

Usage no npm install needed!

README

Sitemap Module

Features

Table of Contents

Installation

Setup

Configuration

Object

Array

Function

Boolean

Usage

Setup a Sitemap

Setup a Sitemap Index

Setup a list of sitemaps

Sitemap Options

routes (optional) - array | function

path (optional) - string

hostname (optional) - string

cacheTime (optional) - number

etag (optional) - object

exclude (optional) - string array

filter (optional) - function

gzip (optional) - boolean

xmlNs (optional) - string

xslUrl (optional) - string

trailingSlash (optional) - boolean

i18n (optional) - string | object

defaults (optional) - object

Sitemap Index Options

path (optional) - string

hostname (optional) - string

sitemaps - array of object

lastmod (optional) - string

etag (optional) - object

gzip (optional) - boolean

xmlNs (optional) - string

xslUrl (optional) - string

Routes Declaration

From a static list

From a function which returns a Promise

Hooks

License

Contributors

`Object`

`Array`

`Function`

`Boolean`

`routes` (optional) - array | function

`path` (optional) - string

`hostname` (optional) - string

`cacheTime` (optional) - number

`etag` (optional) - object

`exclude` (optional) - string array

`filter` (optional) - function

`gzip` (optional) - boolean

`xmlNs` (optional) - string

`xslUrl` (optional) - string

`trailingSlash` (optional) - boolean

`i18n` (optional) - string | object

`defaults` (optional) - object

`path` (optional) - string

`hostname` (optional) - string

`sitemaps` - array of object

`lastmod` (optional) - string

`etag` (optional) - object

`gzip` (optional) - boolean

`xmlNs` (optional) - string

`xslUrl` (optional) - string