Sitemap Generator

Common errors

• XML validation error: Invalid attribute 'xsi:schemaLocation' in XML namespace

  cause Older versions of the validator incorrectly rejected namespace-qualified attributes like `xsi:schemaLocation`.
  fix Upgrade to `sitemap@8.0.2` or newer. This version extended validation to accept such attributes, fixing issue #464.

• Circular dependency breaking Node.js 20.6 / Maximum call stack size exceeded

  cause A circular dependency issue, primarily affecting Node.js 20.6, caused stack overflow errors during package initialization.
  fix Upgrade to `sitemap@7.1.2` or newer, which contains a fix for this specific circular dependency.

Warnings

• breaking Version 9.0.0 dropped support for Node.js versions older than 20.19.5 and npm versions older than 10.8.2. It also transitioned to an ESM-first architecture.
  Fix: Upgrade Node.js to version 20.19.5 or higher and npm to 10.8.2 or higher. Update import statements to ESM syntax if encountering issues, although dual ESM/CJS support is provided.
• breaking The package moved to an ESM-first architecture in v9.0.0, utilizing `"type": "module"` in `package.json` and conditional exports. While CommonJS `require` is still supported for most direct imports, direct file imports might require `.js` extensions.
  Fix: Prefer ESM `import` statements for new code. If directly importing internal files, ensure `.js` extensions are used or rely on the main package exports. Ensure your build system supports dual packages.
• breaking Sitemap generation typically limits a single sitemap file to 50,000 URLs and 50MB (uncompressed). Exceeding these limits can lead to search engines ignoring parts of your sitemap.
  Fix: For sites with more than 50,000 URLs, use `SitemapIndexStream` or `simpleSitemapAndIndex` to automatically create multiple sitemap files and a sitemap index file, which can contain up to 50,000 sitemaps.
• security Multiple XML injection vulnerabilities (BB-01) were fixed, primarily concerning unescaped `xslUrl` in stylesheet processing instructions. Special characters (`&`, `"`, `<`, `>`) were not properly escaped.
  Fix: Upgrade to `sitemap@9.0.1`, `sitemap@8.0.3`, `sitemap@7.1.3`, or newer to ensure XSL URLs are correctly escaped, preventing potential XML injection.
• security Security vulnerabilities (BB-02, BB-03, BB-04, BB-05) related to excessive resource consumption and arbitrary file writes were addressed. These include enforcing 50,000 URL limits in `XMLToSitemapItemStream`, capping parser error arrays to prevent memory DoS, rejecting absolute `destinationDir` paths, and promptly destroying streams when `maxEntries` are exceeded during parsing.
  Fix: Upgrade to `sitemap@9.0.1`, `sitemap@8.0.3`, `sitemap@7.1.3`, or newer to benefit from these robustness and security enhancements. Ensure `destinationDir` for `simpleSitemapAndIndex` is a relative path.

Install

• npm install sitemap npm
• yarn add sitemap yarn
• pnpm add sitemap pnpm

Imports

• SitemapStream
  wrong:

  const { SitemapStream } = require('sitemap')

  correct:

  import { SitemapStream } from 'sitemap'

  While CommonJS `require` still works for basic imports, the package is ESM-first since v9.0.0. Prefer ESM `import`.
• SitemapItem
  wrong:

  import SitemapItem from 'sitemap'

  correct:

  import { SitemapItem } from 'sitemap'

  This is a named export, not a default export.
• streamToPromise
  wrong:

  import { streamToPromise } from 'sitemap/lib/streamToPromise'

  correct:

  import { SitemapStream, streamToPromise } from 'sitemap'

  Common utility to convert a stream to a promise, exported directly from the main package since v9.
• simpleSitemapAndIndex
  wrong:

  const simpleSitemapAndIndex = require('sitemap').simpleSitemapAndIndex

  correct:

  import { simpleSitemapAndIndex } from 'sitemap'

  A convenient function for generating a sitemap index and multiple sitemaps, especially for large sites exceeding 50,000 URLs.

Quickstart

This quickstart demonstrates how to programmatically generate a gzipped sitemap XML file from a list of `SitemapItem` objects using streams, handling common URL properties and image entries.

import { SitemapStream, streamToPromise, SitemapItem } from 'sitemap';
import { createGzip } from 'node:zlib';
import { Readable } from 'node:stream';
import { writeFile } from 'node:fs/promises';

const hostname = process.env.SITE_HOSTNAME ?? 'https://example.com';
const links: SitemapItem[] = [
  { url: '/', changefreq: 'daily', priority: 1.0 },
  { url: '/about', changefreq: 'monthly', priority: 0.7 },
  { url: '/contact', changefreq: 'weekly', priority: 0.5, lastmod: new Date() },
  {
    url: '/products/widget',
    lastmod: '2023-11-20',
    img: [
      { url: `${hostname}/img/widget.jpg`, caption: 'Awesome Widget' },
    ],
  },
  { url: '/blog/post-1', changefreq: 'weekly' },
  { url: '/blog/post-2', lastmod: '2024-01-15', priority: 0.8 },
];

(async () => {
  try {
    const sitemapStream = new SitemapStream({ hostname });
    const pipeline = Readable.from(links).pipe(sitemapStream).pipe(createGzip());
    const sitemapXml = await streamToPromise(pipeline);

    await writeFile('./public/sitemap.xml.gz', sitemapXml);
    console.log('Sitemap generated successfully to public/sitemap.xml.gz');
  } catch (error) {
    console.error('Error generating sitemap:', error);
  }
})();