Skip to Content

Sitemaps

Generate sitemap XML, split files, and publish sitemap indexes.

@puzzle-ui/seo generates sitemap XML from URL entries and can split large collections into multiple files.

Install

npm install @puzzle-ui/seo react

React 19 is a peer dependency. Framework adapters do not require a framework package at runtime.

Quick start

import { generateSitemap } from "@puzzle-ui/seo/sitemap";

const result = generateSitemap({
  baseUrl: "https://example.com",
  entries: [
    { url: "/", changeFrequency: "weekly" },
    { url: "/about", lastModified: "2026-01-01" },
  ],
});
if (result.issues.length) throw new Error(result.issues.map((issue) => issue.message).join("\n"));
// Publish result.indexXml when present, and every result.files entry at its URL.

serializeSitemap produces one { xml, entries, issues } result. generateSitemap returns { files, indexXml, indexUrl, totalEntries, issues }; the index is present only when multiple files are generated. Files use names such as sitemap-1.xml. See Framework Adapters for handlers that publish the index and individual files.

Options

NameTypeDefaultDescription
baseUrlstringrequiredSite origin for relative URLs.
entriesSitemapEntry[]requiredPages to include.
includeLastModifiedbooleantrueControl last-modified serialization.
allowExternalUrlsbooleanfalseAllow external page and alternate URLs.
maxEntriesnumber50000Maximum entries per generated file.
maxBytesnumber52428800Maximum bytes per generated file, from 1024 to 50 MiB.
filenamestring"sitemap"Base for generated file and index names.
validateAlternatesbooleanfalseEnable alternate relationship validation.

A SitemapEntry accepts url, lastModified, changeFrequency, priority, images, videos, and locale alternates. Entries marked indexable: false, with a non-200 statusCode, or with redirectTo are excluded. URLs are normalized, deduplicated and sorted. Check issues: invalid input is not a substitute for application-level URL or publication policy. External images are supported even when external page URLs are disabled.

Exports

@puzzle-ui/seo/sitemap exports serializeSitemap, generateSitemap, validateSitemapEntries, createSitemapXml, serializeSitemapEntry, escapeXml, formatSitemapDate, sitemapByteLength and sitemap types.