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 languages
TypeScript, JavaScript, CSS, Prolog, Shell
Last published
July 14, 2026
@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)
| Field | Description |
|---|
siteName | Globally unique id for this slice. Drives ./sitemaps/<siteName>/ (default storage) and public URLs under /sitemaps/<siteName>/.... Must not duplicate across configs. |
domain | Canonical storefront origin (e.g. https://www.example.com/) used when emitting loc URLs and public shard URLs. |
limit | Max URLs per sitemap-N.xml shard. |
languageCode | Vendure LanguageCode for generation and translation joins. |
channelToken | Channel token used to build RequestContext for that storefront. |
queryBatchSize |
Other options
| Option | Description |
|---|
buildSources | (builtIn) => SitemapSource[]. Default includes catalog and product built-in sources. Compose custom SitemapSource implementations with builtIn.catalog / builtIn.product. |
storage | SitemapStorage. 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:
storage.getRedirectUrl — if set, responds with 302 (e.g. CDN URL).
storage.openReadStream — streams uncompressed XML; response is gzip-encoded with Content-Type: application/xml.
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. Cursor page size when scanning products/collections. Default: min(5000, max(500, limit)). |
getRedirectUrl
resolvePath
urlBuilder | SitemapUrlBuilder. Default: DefaultSitemapUrlBuilder (public shard URLs under .../sitemaps/<siteName>/...). |
refreshTask | Scheduled 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 },
});