{"id":17364,"library":"sitemap","title":"Sitemap Generator","description":"The `sitemap` package is a high-level, streaming library and CLI tool designed for generating and managing XML sitemap files according to the sitemap.org protocol. It facilitates the creation of sitemaps and sitemap indexes, supporting various content types like images, videos, and multilingual alternatives. The package is actively maintained, with version 9.0.1 being the current stable release, frequently issuing security patches across major versions (e.g., 7.x, 8.x, 9.x) and introducing significant breaking changes in major releases like v9.0.0. Key differentiators include its robust, security-focused architecture (addressing XML injection, memory DoS, and arbitrary file writes), stream-based processing for efficiency with large datasets, and a command-line interface for quick generation and validation. It offers comprehensive TypeScript support for type safety and IntelliSense.","status":"active","version":"9.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/ekalinin/sitemap.js","tags":["javascript","sitemap","sitemap.xml","typescript"],"install":[{"cmd":"npm install sitemap","lang":"bash","label":"npm"},{"cmd":"yarn add sitemap","lang":"bash","label":"yarn"},{"cmd":"pnpm add sitemap","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` still works for basic imports, the package is ESM-first since v9.0.0. Prefer ESM `import`.","wrong":"const { SitemapStream } = require('sitemap')","symbol":"SitemapStream","correct":"import { SitemapStream } from 'sitemap'"},{"note":"This is a named export, not a default export.","wrong":"import SitemapItem from 'sitemap'","symbol":"SitemapItem","correct":"import { SitemapItem } from 'sitemap'"},{"note":"Common utility to convert a stream to a promise, exported directly from the main package since v9.","wrong":"import { streamToPromise } from 'sitemap/lib/streamToPromise'","symbol":"streamToPromise","correct":"import { SitemapStream, streamToPromise } from 'sitemap'"},{"note":"A convenient function for generating a sitemap index and multiple sitemaps, especially for large sites exceeding 50,000 URLs.","wrong":"const simpleSitemapAndIndex = require('sitemap').simpleSitemapAndIndex","symbol":"simpleSitemapAndIndex","correct":"import { simpleSitemapAndIndex } from 'sitemap'"}],"quickstart":{"code":"import { SitemapStream, streamToPromise, SitemapItem } from 'sitemap';\nimport { createGzip } from 'node:zlib';\nimport { Readable } from 'node:stream';\nimport { writeFile } from 'node:fs/promises';\n\nconst hostname = process.env.SITE_HOSTNAME ?? 'https://example.com';\nconst links: SitemapItem[] = [\n  { url: '/', changefreq: 'daily', priority: 1.0 },\n  { url: '/about', changefreq: 'monthly', priority: 0.7 },\n  { url: '/contact', changefreq: 'weekly', priority: 0.5, lastmod: new Date() },\n  {\n    url: '/products/widget',\n    lastmod: '2023-11-20',\n    img: [\n      { url: `${hostname}/img/widget.jpg`, caption: 'Awesome Widget' },\n    ],\n  },\n  { url: '/blog/post-1', changefreq: 'weekly' },\n  { url: '/blog/post-2', lastmod: '2024-01-15', priority: 0.8 },\n];\n\n(async () => {\n  try {\n    const sitemapStream = new SitemapStream({ hostname });\n    const pipeline = Readable.from(links).pipe(sitemapStream).pipe(createGzip());\n    const sitemapXml = await streamToPromise(pipeline);\n\n    await writeFile('./public/sitemap.xml.gz', sitemapXml);\n    console.log('Sitemap generated successfully to public/sitemap.xml.gz');\n  } catch (error) {\n    console.error('Error generating sitemap:', error);\n  }\n})();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"*"},{"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.","message":"Multiple XML injection vulnerabilities (BB-01) were fixed, primarily concerning unescaped `xslUrl` in stylesheet processing instructions. Special characters (`&`, `\"`, `<`, `>`) were not properly escaped.","severity":"security","affected_versions":"<9.0.1, <8.0.3, <7.1.3"},{"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.","message":"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.","severity":"security","affected_versions":"<9.0.1, <8.0.3, <7.1.3"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade to `sitemap@8.0.2` or newer. This version extended validation to accept such attributes, fixing issue #464.","cause":"Older versions of the validator incorrectly rejected namespace-qualified attributes like `xsi:schemaLocation`.","error":"XML validation error: Invalid attribute 'xsi:schemaLocation' in XML namespace"},{"fix":"Upgrade to `sitemap@7.1.2` or newer, which contains a fix for this specific circular dependency.","cause":"A circular dependency issue, primarily affecting Node.js 20.6, caused stack overflow errors during package initialization.","error":"Circular dependency breaking Node.js 20.6 / Maximum call stack size exceeded"}],"ecosystem":"npm","meta_description":null}