sitemap

@evolve-framework/sitemap · v1.0.0

Builds a shop's XML sitemaps: it reads every product, category or page from a source, splits them into files of at most 50,000 URLs, and writes the files and their index to file storage.

When to use

Use it to publish sitemaps for a catalog too large to render on request. A commerce engine provides the source, such as CommercetoolsProductSitemapSource or MedusaProductSitemapSource, and a cloud adapter provides the storage the files are written to. Run it as a scheduled job, or as a service whose SitemapModule exposes rebuild routes. A storefront that renders its own sitemap does not need it.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-framework/sitemap @evolve-framework/core fastify

   Requirements3

   @evolve-framework/core	>= 1.0.0 < 2.0.0
   @types/node	>=22optional
   fastify	>= 5.12.1 < 6.0.0

For example:

import {
  consistentPartitions,
  SitemapModule,
  SitemapService,
  SitemapWriter,
} from "@evolve-framework/sitemap";
import { source } from "./catalog.ts"; // from your commerce engine
import { storage } from "./storage.ts"; // from your cloud adapter

const service = new SitemapService({
  source,
  writer: new SitemapWriter({
    storage,
    bucket: "sitemaps",
    collection: "products",
    strategy: consistentPartitions(16),
  }),
  buildUrl: ({ locale, slug }) => `https://shop.example.com/${locale}/p/${slug}`,
});

const module = new SitemapModule({ service, secret: process.env.SITEMAP_SECRET });

Modules

SitemapModule

Hosts sitemap generation as a service.

The job script stays the primary way to run this — a scheduled container or function invoking rebuild() directly. The module exists so the same routine is reachable over HTTP, for a scheduler that can only make a request and for rebuilding a few partitions after a content change without waiting for the next scheduled run.

A rebuild is triggered rather than awaited: walking a catalog outlasts any sensible request timeout, so the route returns 202 and the report is logged.

import { SitemapModule } from "@evolve-framework/sitemap";

new SitemapModule(options: SitemapModuleOptions)

Option	Type	Description
service	SitemapService	The service the routes run: /rebuild calls its rebuild() and /rebuild/partitions its rebuildPartitions().
routes?	boolean	Publish the operational routes (/rebuild, /rebuild/partitions). Disable for a deployment that only runs the job on a schedule. Defaults to true.
secret?	string	Shared secret required on the operational routes. When set, callers must present authorization: Bearer <secret>.

Extends AbstractModule<unknown>.

Entry points

@evolve-framework/sitemap	SitemapService, SitemapWriter, the partition strategies, the source interface and SitemapModule with its rebuild routes.30 exports
@evolve-framework/sitemap/testing	A fake source and entries, for testing a sitemap build without a commerce engine.2 exports