Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SitemapStream
✓ import { SitemapStream } from 'sitemap'
✗ const { SitemapStream } = require('sitemap')
While CommonJS `require` still works for basic imports, the package is ESM-first since v9.0.0. Prefer ESM `import`.
SitemapItem
✓ import { SitemapItem } from 'sitemap'
✗ import SitemapItem from 'sitemap'
This is a named export, not a default export.
streamToPromise
✓ import { SitemapStream, streamToPromise } from 'sitemap'
✗ import { streamToPromise } from 'sitemap/lib/streamToPromise'
Common utility to convert a stream to a promise, exported directly from the main package since v9.
simpleSitemapAndIndex
✓ import { simpleSitemapAndIndex } from 'sitemap'
✗ const simpleSitemapAndIndex = require('sitemap').simpleSitemapAndIndex
A convenient function for generating a sitemap index and multiple sitemaps, especially for large sites exceeding 50,000 URLs.
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);
}
})();
sitemap --version
Debug
Known issues
breakingVersion 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.fixUpgrade 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.
affects: >=9.0.0
breakingThe 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.fixPrefer 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.
affects: >=9.0.0
breakingSitemap 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.fixFor 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.
affects: *
securityMultiple XML injection vulnerabilities (BB-01) were fixed, primarily concerning unescaped `xslUrl` in stylesheet processing instructions. Special characters (`&`, `"`, `<`, `>`) were not properly escaped.fixUpgrade 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.
affects: <9.0.1, <8.0.3, <7.1.3
securitySecurity 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.fixUpgrade 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.
affects: <9.0.1, <8.0.3, <7.1.3
Errors
Common errors & fixes
XML validation error: Invalid attribute 'xsi:schemaLocation' in XML namespace
Older versions of the validator incorrectly rejected namespace-qualified attributes like `xsi:schemaLocation`.
fixUpgrade 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
A circular dependency issue, primarily affecting Node.js 20.6, caused stack overflow errors during package initialization.
fixUpgrade to `sitemap@7.1.2` or newer, which contains a fix for this specific circular dependency.
Audit
Dependencies
No dependency data recorded yet.