API reference

Everything below is exported from @warlock.js/sitemap. The package has zero runtime dependencies and imports nothing from Warlock.

Sitemap

class Sitemap {
  constructor(options: SitemapOptions); // throws InvalidBaseUrlError

  add(entry: SitemapEntry): this; // throws InvalidSitemapEntryError
  addMany(entries: Iterable<SitemapEntry>): this;
  declareRoute(route: string): this;

  get size(): number;
  entries(): readonly ResolvedSitemapEntry[];
  routes(): readonly RouteSummary[];
  duplicates(): readonly DuplicateReport[];

  toXML(): string; // pure, synchronous, repeatable
  saveTo(filePath: string): Promise<void>; // atomic; creates parent dirs
  publishTo(outDir: string, fileName?: string): Promise<string>; // owned-dir publish; default "sitemap.xml"
}

Sitemap keeps every entry in memory, so it is limited to the protocol maximum of 50,000 URLs or 50MB. It satisfies core’s XMLable contract, so response.xml(sitemap) works. See Build a sitemap.

SitemapIndex

class SitemapIndex {
  constructor(options: SitemapIndexOptions); // throws InvalidBaseUrlError, RangeError

  addSource(source: SitemapSourceFactory): this;
  addSource(key: string, source: SitemapSourceFactory): this; // throws DuplicateSourceKeyError

  saveTo(outDir: string): Promise<SitemapSetResult>; // atomic, owned-directory publish
}

SitemapIndex streams entries and writes shards plus a master index. It has no toXML(). See Large sites.

Options

type SitemapOptions = {
  baseUrl: string; // absolute http(s) origin
  changefreq?: ChangeFreq;
  priority?: number;
  lastmod?: string | Date;
};

type SitemapIndexOptions = {
  baseUrl: string;
  filePrefix?: string; // default "sitemap"
  indexFileName?: string; // default "sitemap_index.xml"
  gzip?: boolean; // default false
  maxUrlsPerFile?: number; // default 50_000, never above it
  maxBytesPerFile?: number; // default 50 * 1024 * 1024, never above it
  changefreq?: ChangeFreq;
  priority?: number;
  lastmod?: string | Date;
};

Entries

type SitemapEntry = {
  path: string; // concrete path, or an absolute URL used as given
  name?: string; // diagnostics only; never serialised
  route?: string; // the pattern it came from; feeds routes()/duplicates()
  lastmod?: string | Date; // Date -> toISOString(); string passed through
  changefreq?: ChangeFreq;
  priority?: number; // 0.0–1.0
  alternates?: readonly SitemapAlternate[];
};

type SitemapAlternate = {
  hreflang: string; // any string: "en", "en-GB", "x-default"
  path: string;
};

/** An entry after normalisation: leading slash, defaults folded in, lastmod serialised. */
type ResolvedSitemapEntry = Omit<SitemapEntry, "lastmod"> & { lastmod?: string };

type ChangeFreq = "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";

Diagnostics and results

type RouteSummary = { route: string; count: number }; // count 0 = a declared route produced nothing

type DuplicateReport = {
  path: string;
  count: number; // always >= 2
  routes: readonly (string | undefined)[]; // the route of each add, in order
};

type SitemapSource = Iterable<SitemapEntry> | AsyncIterable<SitemapEntry>;
type SitemapSourceFactory = () => SitemapSource | Promise<SitemapSource>;

type SitemapSetResult = {
  indexPath: string;
  files: readonly SitemapFileResult[];
  totalUrls: number;
  duplicates: readonly DuplicateReport[];
  routes: readonly RouteSummary[];
};

type SitemapFileResult = {
  path: string;
  key?: string; // the source key, when the source was named
  urls: number;
  bytes: number;
  gzipped: boolean;
};

Errors

| Error | Thrown from | When | | --- | --- | --- | | InvalidBaseUrlError | new Sitemap(), new SitemapIndex() | baseUrl is missing, relative, or not http(s). | | InvalidSitemapEntryError | add(), and while SitemapIndex writes | No path, a priority outside 0.0–1.0, an unknown changefreq, an invalid Date, or an alternate with no hreflang. | | DuplicateSourceKeyError | SitemapIndex.addSource() | Two source keys differ only in case, so they would overwrite each other’s shard files. | | UnownedOutputDirectoryError | SitemapIndex.saveTo(), Sitemap.publishTo() | outDir isn’t empty and has no .sitemap-set.json marker. Nothing is written. |

SitemapIndex also throws RangeError from its constructor when maxUrlsPerFile or maxBytesPerFile is above the protocol limit, and from addSource() when a key isn’t a valid filename fragment (letters, digits, -, and _).

Building blocks

function buildSitemapXml(entries: readonly ResolvedSitemapEntry[], baseUrl: string): string;
function renderUrlBlock(entry: ResolvedSitemapEntry, baseUrl: string): string;
function escapeXml(value: string): string;
function joinOrigin(origin: string, routePath: string): string;

buildSitemapXml writes the sitemaps.org urlset document. It uses the correct namespace and element order, declares the xhtml namespace only when an entry has alternates, and escapes &, <, >, ", and '. joinOrigin joins an origin and a path with exactly one slash between them.

Not in this package

Page discovery, the page-level sitemap export, locale expansion, the /sitemap.xml route, robots.txt, and MissingPublicUrlError are part of @warlock.js/web/sitemap. See Sitemap and robots.txt.

Source: @warlock.js/sitemap/src/