Hyperse
  • Pricing
  • FAQs
Newsletter

Subscribe to our newsletter

Receive weekly updates with latest collections and exclusive offers, straight to your inbox.

Hyperse

Headless commerce solutions for brands, developers, and modern ecommerce teams.

Explore

  • Home
  • About Us
  • Partners
  • FAQs

Legal & resources

  • Proposal
  • Privacy Policy
  • Terms & Conditions

© 2026 Hyperse. All rights reserved.


  1. Home
  2. Vendure Plugins
  3. hps-plugin-sitemap
hps-plugin-sitemap

hps-plugin-sitemap

By Yingchun Tian

hps-plugin-sitemap is a Sitemap plugin in the Hub Growth group.hps-plugin-sitemap provides Sitemap plugin capabilities for Hub Growth. Growth, campaigns, loyalty, and customer engagement features. It is especially useful for growth workflows.

CoreVendure Plugins

Specifications

Technical details and package information for this product.

Package

@hyperse-hub/hps-plugin-sitemap

Support by

Yingchun Tian

Support languages

TypeScript, JavaScript, CSS, Prolog, Shell

Integration type

Core

Category

Vendure Plugins

Compatible with

^3.0.0

Latest version

1.0.12

Downloads

0

Repository

https://github.com/hyperse-hub/hub-growth

Last published

July 14, 2026

Description
Changelog
loading...

On this page

  • @hyperse-hub/hps-plugin-sitemap
    • Requirements
    • Installation
    • Registering the plugin
    • Configuration
      • sitemapConfigs (required)
      • Other options
    • HTTP serving
    • Built-in sitemap sources
    • Admin API and permissions
    • Scheduled refresh
    • Package exports
    • License

@hyperse-hub/hps-plugin-sitemap

Vendure plugin that generates and serves XML sitemaps for your storefront. It crawls collections and products per channel and language, shards large catalogs with the sitemap package, persists artifacts via pluggable storage, and exposes Admin API queries and a refresh mutation. A scheduled task can enqueue regeneration jobs on a cron schedule.

Requirements

  • Vendure >= 3.6 (plugin compatibility >= 3.0.0)
  • Node >= 16
  • @hyperse-hub/hps-plugin-admin (the plugin imports it for dashboard extensions)

Install peer dependencies (@vendure/core, Nest, GraphQL, TypeORM, etc.) as usual for your stack.

Installation

Add the package to your Vendure server project and register the plugin (see below).

Registering the plugin

Import HpsPluginSitemap and call init() with at least one entry in sitemapConfigs. Each entry defines a distinct “site slice” identified by a globally unique siteName (storage path segment and public URL segment).

Local dev server reference: config/dev-server.ts in this package.

Configuration

Pass options to HpsPluginSitemap.init({ ... }). Types live in HpsPluginSitemapOptions and SitemapConfig (src/types.ts).

sitemapConfigs (required)

FieldDescription
siteNameGlobally unique id for this slice. Drives ./sitemaps/<siteName>/ (default storage) and public URLs under /sitemaps/<siteName>/.... Must not duplicate across configs.
domainCanonical storefront origin (e.g. https://www.example.com/) used when emitting loc URLs and public shard URLs.
limitMax URLs per sitemap-N.xml shard.
languageCodeVendure LanguageCode for generation and translation joins.
channelTokenChannel token used to build RequestContext for that storefront.
queryBatchSize

Other options

OptionDescription
buildSources(builtIn) => SitemapSource[]. Default includes catalog and product built-in sources. Compose custom SitemapSource implementations with builtIn.catalog / builtIn.product.
storageSitemapStorage. Default: LocalFsSitemapStorage, writing under ./sitemaps/<siteName>/. Implement write, and for HTTP serving openReadStream, , and/or legacy .

HTTP serving

The plugin registers SitemapController at /sitemaps (see sitemapDirName in src/constants.ts).

Requests match /sitemaps/:siteName/*. Resolution order:

  1. storage.getRedirectUrl — if set, responds with 302 (e.g. CDN URL).
  2. storage.openReadStream — streams uncompressed XML; response is gzip-encoded with Content-Type: application/xml.
  3. storage.resolvePath + local file read (legacy local layout).

Built-in sitemap sources

  • CatalogSitemapSource (key: 'catalog') — Collection URLs for the configured channel, batched by id.
  • ProductSitemapSource (key: 'product') — Product URLs for the configured channel, batched by id.

Custom sources implement SitemapSource: a key and getLinks({ ctx, injector, sitemapConfig }) returning SitemapItemLoose entries.

Admin API and permissions

Admin schema extensions include:

  • Query.sitemap / Query.sitemaps — list and inspect generation runs (Sitemap entity: status, timings, index path, parts, errors, etc.).
  • Mutation.refreshSiteMap — enqueue regeneration jobs for all or specific targets matching sitemapConfigs.

Grant the custom permission AllowSitemapPermission (src/config/sitemap-permission.ts) to roles that should trigger refresh or read sitemap admin data.

Scheduled refresh

When refreshTask.enabled is not false, the plugin pushes a ScheduledTask (hps-plugin-sitemap-refresh-sitemap-task) that calls SitemapGeneratorService.createJobTask, optionally restricted to refreshTask.targets.

Disable with:

Package exports

The package entry re-exports the plugin, types, contracts (sources, storage, URL builder, tokens), services, built-in sources, and sitemapPermission for server integration and testing.

License

MIT — see LICENSE in the repository.

import { LanguageCode } from '@vendure/core';
import { HpsPluginSitemap } from '@hyperse-hub/hps-plugin-sitemap';
export const config = {
plugins: [
HpsPluginSitemap.init({
sitemapConfigs: [
{
siteName: 'default-en',
domain: 'https://www.example.com/',
limit: 50_000,
languageCode: LanguageCode.en,
channelToken: 'default-channel',
},
],
// Optional: customize sources, storage, URL builder, refresh task — see Configuration
}),
],
};
Optional. Cursor page size when scanning products/collections. Default: min(5000, max(500, limit)).
getRedirectUrl
resolvePath
urlBuilderSitemapUrlBuilder. Default: DefaultSitemapUrlBuilder (public shard URLs under .../sitemaps/<siteName>/...).
refreshTaskScheduled task (Vendure scheduler). enabled: default true. schedule: default daily at 00:00. targets: optional subset of { siteName, channelToken, languageCode } to enqueue; otherwise all configs.
HpsPluginSitemap.init({
sitemapConfigs: [/* ... */],
refreshTask: { enabled: false },
});