@whatworks/payload-sitemap 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 What Works Global
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @whatworks/payload-sitemap
+
+Chunked, lazily cached XML sitemaps for [Payload](https://payloadcms.com) with hook-driven invalidation and robots.txt helpers.
+
+Next.js + Vercel work with near-zero config; every layer — delivery, caching, invalidation, robots output — is overridable for other stacks (decoupled frontends, self-hosted servers, SSG builds).
+
+## How it works
+
+- **Lazy generation.** Nothing regenerates on save. Collection hooks only mark a group's cache dirty (deduped per request, run after the response so the transaction has committed). The next sitemap request regenerates that group from the database — slug changes, breadcrumb cascades (e.g. `plugin-nested-docs` re-saving children), publishes, unpublishes, and deletes all come out correct without any change detection.
+- **One sitemap file per collection, chunked.** `/sitemap.xml` is a `<sitemapindex>` referencing `pages-1.xml`, `posts-1.xml`, … split at `chunkSize` (default 25,000; protocol limit 50,000).
+- **Lean queries.** Docs are fetched in pages of 1,000 with `select`, `depth: 0`, and a `_status` filter applied only when the collection actually has drafts enabled.
+- **Caching:** with `'auto'` (default), entries are cached in the Next.js Data Cache with tags (`revalidateTag` invalidation — works across serverless instances on Vercel) and fall back to an in-memory cache outside Next. Responses also carry `Cache-Control: s-maxage` so a CDN absorbs crawler traffic.
+
+## Quick start (Payload inside Next.js)
+
+```ts
+// payload.config.ts
+import { sitemapPlugin } from '@whatworks/payload-sitemap'
+
+export default buildConfig({
+  plugins: [
+    sitemapPlugin({
+      collections: {
+        pages: {
+          path: ({ doc }) => (doc.slug === 'home' ? '/' : `/${doc.slug}`),
+          select: { slug: true },
+        },
+      },
+    }),
+  ],
+})
+```
+
+```ts
+// app/sitemap.xml/route.ts
+import config from '@payload-config'
+import { createSitemapIndexRoute } from '@whatworks/payload-sitemap/next'
+
+export const dynamic = 'force-dynamic'
+export const { GET } = createSitemapIndexRoute({ config })
+```
+
+```ts
+// app/sitemaps/[sitemap]/route.ts
+import config from '@payload-config'
+import { createSitemapChunkRoute } from '@whatworks/payload-sitemap/next'
+
+export const dynamic = 'force-dynamic'
+export const { GET } = createSitemapChunkRoute({ config })
+```
+
+```ts
+// app/robots.ts
+import config from '@payload-config'
+import { createRobots } from '@whatworks/payload-sitemap/next'
+
+export default createRobots({ config })
+```
+
+This is the entire setup — no env vars required. `robots.txt` disallows everything outside production (`VERCEL_ENV`/`NODE_ENV`), and disallows the admin + API routes in production.
+
+### How `siteUrl` is resolved
+
+Every URL in the sitemap is joined onto the first available of:
+
+1. the `siteUrl` plugin option — a string, or a function `({ request }) => string` with full control
+2. `SITE_URL` → `NEXT_PUBLIC_SERVER_URL` → `https://$VERCEL_PROJECT_PRODUCTION_URL`
+3. **the incoming request** — `x-forwarded-proto`/`x-forwarded-host`, then `Host`, then the request URL's origin
+
+Env vars deliberately outrank the request: a deployment is often reachable via
+non-canonical aliases (`*.vercel.app`, internal hostnames), and an SEO artifact should
+emit the canonical domain when one is declared. Set `SITE_URL` (or the option) in
+production if your app answers on more than one host; skip it entirely and the sitemap
+simply mirrors whatever host it was requested on.
+
+Host headers are client-controlled, so request-derived origins are never written to the
+shared cache — entries are cached as site-relative paths and joined onto the resolved
+origin per request. A forged `Host` can only distort the forger's own response.
+
+## Plugin options
+
+```ts
+sitemapPlugin({
+  // Required. Per-collection config, typed against your generated types.
+  collections: {
+    pages: {
+      // Return a path (joined to siteUrl) or an absolute URL (used verbatim).
+      // Return null/undefined to omit the doc.
+      path: ({ doc }) => `/${doc.slug}`,
+      // Fields your path()/lastMod() need. id/updatedAt are always included.
+      select: { slug: true, breadcrumbs: true },
+      lastMod: 'publishedAt', // field name, (doc) => Date, or false. Default 'updatedAt'
+      where: {}, // extra query constraints
+      chunkSize: 10_000, // per-collection override
+      changeFreq: 'weekly', // opt-in; Google ignores it
+      priority: 0.5, // opt-in; Google ignores it
+      // Override the default invalidation heuristic (invalidate on any change
+      // except a draft save with no published transition):
+      shouldInvalidate: ({ doc, previousDoc, operation }) => true,
+    },
+  },
+
+  // String, or a function with full control (multi-tenant, per-request logic).
+  // Default: env chain → incoming request (see “How siteUrl is resolved”).
+  siteUrl: ({ request }) => `https://${request.headers.get('host')}`,
+  trailingSlash: false,
+  chunkSize: 25_000,
+
+  // Extra routes: static array, or an async function (e.g. read a global).
+  routes: async ({ payload }) => [{ path: '/search' }],
+
+  // Injected admin fields. Default: an `excludeFromSitemap` sidebar checkbox.
+  // `group` nests them inside the group field (or named tab) with that name —
+  // e.g. an existing `metadata` group. Dot notation reaches nested containers
+  // (`'seo.metadata'`); missing segments are created as groups on collections
+  // that lack them. The exclude flag then lives at `metadata.excludeFromSitemap`.
+  adminFields: { exclude: true, group: 'metadata' },
+
+  // 'auto' (default) | 'memory' | 'none' | custom { wrap, invalidate } adapter.
+  cache: 'auto',
+
+  // REST endpoints under the API route. DISABLED by default — the Next route
+  // handlers above are the primary delivery.
+  endpoints: {
+    path: '/sitemap', // → /api/sitemap/index.xml, /api/sitemap/pages-1.xml
+    access: ({ req }) => true, // XML access; default public once enabled
+    json: true, // /api/sitemap/entries.json; default access: req.user
+    cacheControl: 'public, max-age=0, s-maxage=600, stale-while-revalidate=86400',
+    origin: 'https://cms.example.com', // index chunk-URL origin; default: request origin
+  },
+
+  // Defaults for robots output (createRobots / generateRobotsTxt).
+  robots: {
+    isProduction: undefined, // default VERCEL_ENV/NODE_ENV
+    disallow: ['/drafts/'], // appended to the default rule
+    rules: undefined, // replace default rules entirely
+    sitemaps: undefined, // default `${siteUrl}/sitemap.xml`
+    transform: (robots) => robots, // final say over the computed output
+  },
+
+  disabled: false, // keeps injected fields for schema/migration consistency
+})
+```
+
+## Decoupled frontends & other stacks
+
+Payload standalone as a headless CMS, frontend elsewhere (Astro, SvelteKit, …):
+
+1. **Enable the REST endpoints** (`endpoints: true`). The sitemap serves from
+   `https://cms.example.com/api/sitemap/index.xml`.
+2. Either **proxy** `/sitemap.xml` → the CMS endpoint from your frontend, or declare it
+   cross-host in the frontend's robots.txt (sanctioned by sitemaps.org):
+   `Sitemap: https://cms.example.com/api/sitemap/index.xml`
+3. For **build-time SSG**, fetch `/api/sitemap/entries.json` (authenticated by default)
+   or call `getSitemapEntries(payload)` in a build script and render however you like.
+4. `generateRobotsTxt(config, overrides?)` returns a robots.txt string for any server.
+
+On a long-running self-hosted server, set `cache: 'memory'` — hooks invalidate it
+in-process. For anything else, implement the two-method `SitemapCache` interface
+(`wrap`, `invalidate`) — e.g. backed by Redis — and pass it as `cache`.
+
+## Public API
+
+| Export (`.`)                                                                    | Purpose                                                             |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `sitemapPlugin(config)`                                                         | The Payload plugin                                                  |
+| `getSitemapEntries(payload, opts?)`                                             | All cached entries keyed by group                                   |
+| `invalidateSitemap(payload, groups?)`                                           | Manual invalidation (e.g. from a global's hook that feeds `routes`) |
+| `generateRobotsTxt(config, overrides?)`                                         | robots.txt string for any delivery                                  |
+| `getIndexItems` / `getChunkEntries` / `buildUrlsetXml` / `buildSitemapIndexXml` | Building blocks for custom delivery                                 |
+| `SITEMAP_CACHE_TAG` / `sitemapCacheTag(group)`                                  | Next cache tags, for custom `revalidateTag` calls                   |
+
+| Export (`./next`)                                                 | Purpose                                             |
+| ----------------------------------------------------------------- | --------------------------------------------------- |
+| `createSitemapIndexRoute({ config, chunksPath?, cacheControl? })` | `GET` handler for `app/sitemap.xml/route.ts`        |
+| `createSitemapChunkRoute({ config, param?, cacheControl? })`      | `GET` handler for `app/sitemaps/[sitemap]/route.ts` |
+| `createRobots({ config, ...robotsOverrides })`                    | Default export for `app/robots.ts`                  |
+
+## Development
+
+`pnpm dev` (from `packages/sitemap`) boots the sandbox in `dev/` — a Next app with the
+admin at [/admin](http://localhost:3000/admin) (login form comes prefilled) and a demo
+page at [/](http://localhost:3000) listing every delivery surface plus the live cached
+entries. It seeds a drafts-enabled `pages` collection, a draftless `legal` collection,
+a draft-only doc and an `excludeFromSitemap` doc into a throwaway SQLite database
+(`dev/.dbs/`, gitignored — delete it to reseed). Publish/delete docs in the admin and
+reload to watch hook-driven invalidation land.
+
+## Notes
+
+- **`changefreq`/`priority` are opt-in** because Google ignores both; `lastmod` is the
+  only freshness signal it uses. Skipping them keeps the admin sidebar and XML lean.
+- **Invalidation timing:** hooks schedule invalidation via Next's `after()` (post-response,
+  post-commit; uses `waitUntil` on Vercel) with a plain macrotask fallback outside Next.
+  `revalidateTag` is called with `{ expire: 0 }` for instant expiry on Next 16; Next 15
+  ignores the extra argument.
+- **CDN staleness trade-off:** the default `s-maxage=600` means a CDN may serve a
+  sitemap up to 10 minutes stale after a publish — regeneration is cheap behind it, so
+  tune `cacheControl` if you need tighter freshness.
+- Drafts are never included: the `_status` filter applies exactly when the collection
+  has drafts enabled, so collections without drafts also work (no `_status` query error).

package/dist/exports/next.d.ts

@@ -0,0 +1,78 @@
+import { o as RobotsOptions } from "../types-j8T8euN5.js";
+import { SanitizedConfig } from "payload";
+import { MetadataRoute } from "next";
+
+//#region src/exports/next.d.ts
+type PayloadConfigInput = Promise<SanitizedConfig> | SanitizedConfig;
+type RouteFactoryArgs = {
+  /** `Cache-Control` header for the response. */
+  cacheControl?: string;
+  config: PayloadConfigInput;
+};
+/**
+ * Route handler for the sitemap index.
+ *
+ * ```ts
+ * // app/sitemap.xml/route.ts
+ * import config from '@payload-config'
+ * import { createSitemapIndexRoute } from '@whatworks/payload-sitemap/next'
+ *
+ * export const dynamic = 'force-dynamic'
+ * export const { GET } = createSitemapIndexRoute({ config })
+ * ```
+ */
+declare const createSitemapIndexRoute: ({
+  cacheControl,
+  chunksPath,
+  config
+}: {
+  /** Public path prefix where the chunk route is mounted. @default '/sitemaps' */
+  chunksPath?: string;
+} & RouteFactoryArgs) => {
+  GET: (request: Request) => Promise<Response>;
+};
+/**
+ * Route handler for individual sitemap chunk files.
+ *
+ * ```ts
+ * // app/sitemaps/[sitemap]/route.ts
+ * import config from '@payload-config'
+ * import { createSitemapChunkRoute } from '@whatworks/payload-sitemap/next'
+ *
+ * export const dynamic = 'force-dynamic'
+ * export const { GET } = createSitemapChunkRoute({ config })
+ * ```
+ */
+declare const createSitemapChunkRoute: ({
+  cacheControl,
+  config,
+  param
+}: {
+  /** Name of the dynamic segment the route is mounted under. @default 'sitemap' */
+  param?: string;
+} & RouteFactoryArgs) => {
+  GET: (request: Request, ctx: {
+    params: Promise<Record<string, string | string[] | undefined>>;
+  }) => Promise<Response>;
+};
+/**
+ * Default export for `app/robots.ts`. Plugin-level `robots` options apply first,
+ * factory overrides win, and `transform` gets the final say.
+ *
+ * ```ts
+ * // app/robots.ts
+ * import config from '@payload-config'
+ * import { createRobots } from '@whatworks/payload-sitemap/next'
+ *
+ * export default createRobots({ config })
+ * ```
+ */
+declare const createRobots: ({
+  config,
+  ...overrides
+}: {
+  config: PayloadConfigInput;
+} & RobotsOptions) => (() => Promise<MetadataRoute.Robots>);
+//#endregion
+export { createRobots, createSitemapChunkRoute, createSitemapIndexRoute };
+//# sourceMappingURL=next.d.ts.map

package/dist/exports/next.js

@@ -0,0 +1,118 @@
+import { _ as getSitemapConfig, c as getChunkEntries, d as finalizeEntries, h as DEFAULT_CACHE_CONTROL, i as buildRobotsData, l as getIndexItems, n as buildUrlsetXml, t as buildSitemapIndexXml } from "../xml-DSOM2moN.js";
+import { getPayload } from "payload";
+
+//#region src/exports/next.ts
+const xmlResponse = (xml, cacheControl) => new Response(xml, { headers: {
+	"Cache-Control": cacheControl,
+	"Content-Type": "application/xml; charset=utf-8"
+} });
+/**
+* Metadata routes receive no request object, so when the site origin isn't
+* statically configured fall back to the request headers via `next/headers`
+* (which makes the route dynamic).
+*/
+const resolveRobotsSiteUrl = async (sitemapConfig) => {
+	try {
+		return sitemapConfig.siteUrl();
+	} catch (staticError) {
+		try {
+			const { headers } = await import("next/headers");
+			return sitemapConfig.siteUrl({ request: { headers: await headers() } });
+		} catch {
+			throw staticError;
+		}
+	}
+};
+/**
+* Route handler for the sitemap index.
+*
+* ```ts
+* // app/sitemap.xml/route.ts
+* import config from '@payload-config'
+* import { createSitemapIndexRoute } from '@whatworks/payload-sitemap/next'
+*
+* export const dynamic = 'force-dynamic'
+* export const { GET } = createSitemapIndexRoute({ config })
+* ```
+*/
+const createSitemapIndexRoute = ({ cacheControl = DEFAULT_CACHE_CONTROL, chunksPath = "/sitemaps", config }) => ({ GET: async (request) => {
+	const payload = await getPayload({ config: await config });
+	const sitemapConfig = getSitemapConfig(payload.config);
+	const base = `${sitemapConfig.siteUrl({ request })}${chunksPath}`;
+	return xmlResponse(buildSitemapIndexXml(await getIndexItems({
+		chunkUrl: (file) => `${base}/${file}`,
+		config: sitemapConfig,
+		payload
+	})), cacheControl);
+} });
+/**
+* Route handler for individual sitemap chunk files.
+*
+* ```ts
+* // app/sitemaps/[sitemap]/route.ts
+* import config from '@payload-config'
+* import { createSitemapChunkRoute } from '@whatworks/payload-sitemap/next'
+*
+* export const dynamic = 'force-dynamic'
+* export const { GET } = createSitemapChunkRoute({ config })
+* ```
+*/
+const createSitemapChunkRoute = ({ cacheControl = DEFAULT_CACHE_CONTROL, config, param = "sitemap" }) => ({ GET: async (request, ctx) => {
+	const rawFile = (await ctx.params)[param];
+	const file = Array.isArray(rawFile) ? rawFile[0] : rawFile;
+	if (!file) return new Response("Not found", { status: 404 });
+	const payload = await getPayload({ config: await config });
+	const sitemapConfig = getSitemapConfig(payload.config);
+	const chunk = await getChunkEntries({
+		config: sitemapConfig,
+		file,
+		payload
+	});
+	if (!chunk) return new Response("Not found", { status: 404 });
+	const collConfig = sitemapConfig.collections[chunk.group];
+	return xmlResponse(buildUrlsetXml(finalizeEntries(chunk.entries, {
+		siteUrl: sitemapConfig.siteUrl({ request }),
+		trailingSlash: sitemapConfig.trailingSlash
+	}), {
+		changeFreq: collConfig?.changeFreq,
+		priority: collConfig?.priority
+	}), cacheControl);
+} });
+/**
+* Default export for `app/robots.ts`. Plugin-level `robots` options apply first,
+* factory overrides win, and `transform` gets the final say.
+*
+* ```ts
+* // app/robots.ts
+* import config from '@payload-config'
+* import { createRobots } from '@whatworks/payload-sitemap/next'
+*
+* export default createRobots({ config })
+* ```
+*/
+const createRobots = ({ config, ...overrides }) => {
+	return async () => {
+		const awaited = await config;
+		const sitemapConfig = getSitemapConfig(awaited);
+		const options = {
+			...sitemapConfig.robots,
+			...overrides
+		};
+		const sitemaps = options.sitemaps ?? [`${await resolveRobotsSiteUrl(sitemapConfig)}/sitemap.xml`];
+		const data = buildRobotsData({
+			adminRoute: awaited.routes.admin,
+			apiRoute: awaited.routes.api,
+			options,
+			sitemaps
+		});
+		return {
+			rules: data.rules,
+			...data.sitemaps.length ? { sitemap: data.sitemaps.length === 1 ? data.sitemaps[0] : data.sitemaps } : {},
+			...data.host ? { host: data.host } : {}
+		};
+	};
+};
+
+//#endregion
+export { createRobots, createSitemapChunkRoute, createSitemapIndexRoute };
+//# sourceMappingURL=next.js.map

package/dist/exports/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","names":[],"sources":["../../src/exports/next.ts"],"sourcesContent":["import type { MetadataRoute } from 'next'\nimport type { SanitizedConfig } from 'payload'\n\nimport { getPayload } from 'payload'\n\nimport type { RobotsOptions } from '../types.js'\n\nimport { getChunkEntries, getIndexItems } from '../core/chunks.js'\nimport { finalizeEntries } from '../core/entries.js'\nimport { DEFAULT_CACHE_CONTROL, getSitemapConfig } from '../core/resolved.js'\nimport { buildRobotsData } from '../core/robots.js'\nimport { buildSitemapIndexXml, buildUrlsetXml } from '../core/xml.js'\n\ntype PayloadConfigInput = Promise<SanitizedConfig> | SanitizedConfig\n\ntype RouteFactoryArgs = {\n  /** `Cache-Control` header for the response. */\n  cacheControl?: string\n  config: PayloadConfigInput\n}\n\nconst xmlResponse = (xml: string, cacheControl: string): Response =>\n  new Response(xml, {\n    headers: {\n      'Cache-Control': cacheControl,\n      'Content-Type': 'application/xml; charset=utf-8',\n    },\n  })\n\n/**\n * Metadata routes receive no request object, so when the site origin isn't\n * statically configured fall back to the request headers via `next/headers`\n * (which makes the route dynamic).\n */\nconst resolveRobotsSiteUrl = async (\n  sitemapConfig: ReturnType<typeof getSitemapConfig>,\n): Promise<string> => {\n  try {\n    return sitemapConfig.siteUrl()\n  } catch (staticError) {\n    try {\n      const { headers } = await import('next/headers')\n      return sitemapConfig.siteUrl({ request: { headers: await headers() } })\n    } catch {\n      throw staticError\n    }\n  }\n}\n\n/**\n * Route handler for the sitemap index.\n *\n * ```ts\n * // app/sitemap.xml/route.ts\n * import config from '@payload-config'\n * import { createSitemapIndexRoute } from '@whatworks/payload-sitemap/next'\n *\n * export const dynamic = 'force-dynamic'\n * export const { GET } = createSitemapIndexRoute({ config })\n * ```\n */\nexport const createSitemapIndexRoute = ({\n  cacheControl = DEFAULT_CACHE_CONTROL,\n  chunksPath = '/sitemaps',\n  config,\n}: {\n  /** Public path prefix where the chunk route is mounted. @default '/sitemaps' */\n  chunksPath?: string\n} & RouteFactoryArgs): { GET: (request: Request) => Promise<Response> } => ({\n  GET: async (request) => {\n    const payload = await getPayload({ config: await config })\n    const sitemapConfig = getSitemapConfig(payload.config)\n    const base = `${sitemapConfig.siteUrl({ request })}${chunksPath}`\n    const items = await getIndexItems({\n      chunkUrl: (file) => `${base}/${file}`,\n      config: sitemapConfig,\n      payload,\n    })\n    return xmlResponse(buildSitemapIndexXml(items), cacheControl)\n  },\n})\n\n/**\n * Route handler for individual sitemap chunk files.\n *\n * ```ts\n * // app/sitemaps/[sitemap]/route.ts\n * import config from '@payload-config'\n * import { createSitemapChunkRoute } from '@whatworks/payload-sitemap/next'\n *\n * export const dynamic = 'force-dynamic'\n * export const { GET } = createSitemapChunkRoute({ config })\n * ```\n */\nexport const createSitemapChunkRoute = ({\n  cacheControl = DEFAULT_CACHE_CONTROL,\n  config,\n  param = 'sitemap',\n}: {\n  /** Name of the dynamic segment the route is mounted under. @default 'sitemap' */\n  param?: string\n} & RouteFactoryArgs): {\n  GET: (\n    request: Request,\n    ctx: { params: Promise<Record<string, string | string[] | undefined>> },\n  ) => Promise<Response>\n} => ({\n  GET: async (request, ctx) => {\n    const params = await ctx.params\n    const rawFile = params[param]\n    const file = Array.isArray(rawFile) ? rawFile[0] : rawFile\n    if (!file) {\n      return new Response('Not found', { status: 404 })\n    }\n\n    const payload = await getPayload({ config: await config })\n    const sitemapConfig = getSitemapConfig(payload.config)\n    const chunk = await getChunkEntries({ config: sitemapConfig, file, payload })\n    if (!chunk) {\n      return new Response('Not found', { status: 404 })\n    }\n\n    const collConfig = sitemapConfig.collections[chunk.group]\n    const entries = finalizeEntries(chunk.entries, {\n      siteUrl: sitemapConfig.siteUrl({ request }),\n      trailingSlash: sitemapConfig.trailingSlash,\n    })\n    const xml = buildUrlsetXml(entries, {\n      changeFreq: collConfig?.changeFreq,\n      priority: collConfig?.priority,\n    })\n    return xmlResponse(xml, cacheControl)\n  },\n})\n\n/**\n * Default export for `app/robots.ts`. Plugin-level `robots` options apply first,\n * factory overrides win, and `transform` gets the final say.\n *\n * ```ts\n * // app/robots.ts\n * import config from '@payload-config'\n * import { createRobots } from '@whatworks/payload-sitemap/next'\n *\n * export default createRobots({ config })\n * ```\n */\nexport const createRobots = ({\n  config,\n  ...overrides\n}: { config: PayloadConfigInput } & RobotsOptions): (() => Promise<MetadataRoute.Robots>) => {\n  return async () => {\n    const awaited = await config\n    const sitemapConfig = getSitemapConfig(awaited)\n    const options = { ...sitemapConfig.robots, ...overrides }\n    const sitemaps = options.sitemaps ?? [\n      `${await resolveRobotsSiteUrl(sitemapConfig)}/sitemap.xml`,\n    ]\n\n    const data = buildRobotsData({\n      adminRoute: awaited.routes.admin,\n      apiRoute: awaited.routes.api,\n      options,\n      sitemaps,\n    })\n\n    return {\n      rules: data.rules,\n      ...(data.sitemaps.length\n        ? { sitemap: data.sitemaps.length === 1 ? data.sitemaps[0] : data.sitemaps }\n        : {}),\n      ...(data.host ? { host: data.host } : {}),\n    }\n  }\n}\n"],"mappings":";;;;AAqBA,MAAM,eAAe,KAAa,iBAChC,IAAI,SAAS,KAAK,EAChB,SAAS;CACP,iBAAiB;CACjB,gBAAgB;CACjB,EACF,CAAC;;;;;;AAOJ,MAAM,uBAAuB,OAC3B,kBACoB;AACpB,KAAI;AACF,SAAO,cAAc,SAAS;UACvB,aAAa;AACpB,MAAI;GACF,MAAM,EAAE,YAAY,MAAM,OAAO;AACjC,UAAO,cAAc,QAAQ,EAAE,SAAS,EAAE,SAAS,MAAM,SAAS,EAAE,EAAE,CAAC;UACjE;AACN,SAAM;;;;;;;;;;;;;;;;AAiBZ,MAAa,2BAA2B,EACtC,eAAe,uBACf,aAAa,aACb,cAI0E,EAC1E,KAAK,OAAO,YAAY;CACtB,MAAM,UAAU,MAAM,WAAW,EAAE,QAAQ,MAAM,QAAQ,CAAC;CAC1D,MAAM,gBAAgB,iBAAiB,QAAQ,OAAO;CACtD,MAAM,OAAO,GAAG,cAAc,QAAQ,EAAE,SAAS,CAAC,GAAG;AAMrD,QAAO,YAAY,qBALL,MAAM,cAAc;EAChC,WAAW,SAAS,GAAG,KAAK,GAAG;EAC/B,QAAQ;EACR;EACD,CAAC,CAC4C,EAAE,aAAa;GAEhE;;;;;;;;;;;;;AAcD,MAAa,2BAA2B,EACtC,eAAe,uBACf,QACA,QAAQ,iBASJ,EACJ,KAAK,OAAO,SAAS,QAAQ;CAE3B,MAAM,WADS,MAAM,IAAI,QACF;CACvB,MAAM,OAAO,MAAM,QAAQ,QAAQ,GAAG,QAAQ,KAAK;AACnD,KAAI,CAAC,KACH,QAAO,IAAI,SAAS,aAAa,EAAE,QAAQ,KAAK,CAAC;CAGnD,MAAM,UAAU,MAAM,WAAW,EAAE,QAAQ,MAAM,QAAQ,CAAC;CAC1D,MAAM,gBAAgB,iBAAiB,QAAQ,OAAO;CACtD,MAAM,QAAQ,MAAM,gBAAgB;EAAE,QAAQ;EAAe;EAAM;EAAS,CAAC;AAC7E,KAAI,CAAC,MACH,QAAO,IAAI,SAAS,aAAa,EAAE,QAAQ,KAAK,CAAC;CAGnD,MAAM,aAAa,cAAc,YAAY,MAAM;AASnD,QAAO,YAJK,eAJI,gBAAgB,MAAM,SAAS;EAC7C,SAAS,cAAc,QAAQ,EAAE,SAAS,CAAC;EAC3C,eAAe,cAAc;EAC9B,CAAC,EACkC;EAClC,YAAY,YAAY;EACxB,UAAU,YAAY;EACvB,CAAC,EACsB,aAAa;GAExC;;;;;;;;;;;;;AAcD,MAAa,gBAAgB,EAC3B,QACA,GAAG,gBACwF;AAC3F,QAAO,YAAY;EACjB,MAAM,UAAU,MAAM;EACtB,MAAM,gBAAgB,iBAAiB,QAAQ;EAC/C,MAAM,UAAU;GAAE,GAAG,cAAc;GAAQ,GAAG;GAAW;EACzD,MAAM,WAAW,QAAQ,YAAY,CACnC,GAAG,MAAM,qBAAqB,cAAc,CAAC,cAC9C;EAED,MAAM,OAAO,gBAAgB;GAC3B,YAAY,QAAQ,OAAO;GAC3B,UAAU,QAAQ,OAAO;GACzB;GACA;GACD,CAAC;AAEF,SAAO;GACL,OAAO,KAAK;GACZ,GAAI,KAAK,SAAS,SACd,EAAE,SAAS,KAAK,SAAS,WAAW,IAAI,KAAK,SAAS,KAAK,KAAK,UAAU,GAC1E,EAAE;GACN,GAAI,KAAK,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,EAAE;GACzC"}

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+import { _ as SitemapRoute, a as RobotsData, b as resolveSiteUrl, c as SitemapCache, d as SitemapEndpointAccess, f as SitemapEndpointsConfig, g as SitemapPluginConfig, h as SitemapPathArgs, i as ResolvedSitemapEndpoints, l as SitemapCollectionConfig, m as SitemapInvalidateArgs, n as InternalSitemapCollectionConfig, o as RobotsOptions, p as SitemapEntry, r as ResolvedSitemapConfig, s as RobotsRule, t as ChangeFrequency, u as SitemapCollections, v as SitemapRoutesFn, x as siteUrlFromRequest, y as SiteUrlContext } from "./types-j8T8euN5.js";
+import { Payload, PayloadRequest, Plugin, SanitizedConfig } from "payload";
+
+//#region src/core/cache.d.ts
+declare const SITEMAP_CACHE_TAG = "payload-sitemap";
+declare const sitemapCacheTag: (group: string) => string;
+declare const createMemoryCache: () => SitemapCache;
+declare const noopCache: SitemapCache;
+/**
+ * Caches entries in the Next.js Data Cache tagged `payload-sitemap:<group>`, so
+ * invalidation is `revalidateTag` — shared across serverless instances on Vercel.
+ * Degrades to uncached execution when `next/cache` is unavailable or errors
+ * (standalone Payload, seed scripts, non-request contexts).
+ */
+declare const createNextTagsCache: () => SitemapCache;
+//#endregion
+//#region src/core/chunks.d.ts
+declare const chunkFileName: (group: string, index: number) => string;
+/**
+ * Matches a chunk filename against the known groups by prefix, so group slugs
+ * containing hyphens or digits parse unambiguously.
+ */
+declare const matchChunkFile: (file: string, groups: string[]) => {
+  group: string;
+  index: number;
+} | null;
+type BaseArgs = {
+  config: ResolvedSitemapConfig;
+  payload: Payload;
+  req?: PayloadRequest;
+};
+/** Items for the `<sitemapindex>`: one per chunk of each non-empty group. */
+declare const getIndexItems: (args: {
+  chunkUrl: (file: string) => string;
+} & BaseArgs) => Promise<Array<{
+  lastmod?: string;
+  loc: string;
+}>>;
+/**
+ * Entries for one chunk file, or `null` when the filename matches no group/range.
+ * `loc` values are site-relative — pass through `finalizeEntries` before rendering.
+ */
+declare const getChunkEntries: (args: {
+  file: string;
+} & BaseArgs) => Promise<{
+  entries: SitemapEntry[];
+  group: string;
+} | null>;
+//#endregion
+//#region src/core/entries.d.ts
+declare const formatLoc: (path: string, siteUrl: string, trailingSlash: boolean) => string;
+/**
+ * Joins cached site-relative entries onto the resolved site origin. Entries are
+ * cached with relative `loc` paths so cached data is host-independent — a
+ * request-derived siteUrl can never leak into the shared cache.
+ */
+declare const finalizeEntries: (entries: SitemapEntry[], {
+  siteUrl,
+  trailingSlash
+}: {
+  siteUrl: string;
+  trailingSlash: boolean;
+}) => SitemapEntry[];
+type FetchArgs = {
+  config: ResolvedSitemapConfig;
+  payload: Payload;
+  req?: PayloadRequest;
+};
+/**
+ * Cached entries for one group (a collection slug or `ROUTES_GROUP`).
+ * `loc` values are site-relative — pass through `finalizeEntries` before rendering.
+ */
+declare const getGroupEntries: (args: {
+  group: string;
+} & FetchArgs) => Promise<SitemapEntry[]>;
+/**
+ * All sitemap entries with absolute URLs, keyed by group. Public API for SSG
+ * frontends and custom delivery — reads the plugin config from the Payload
+ * instance. Pass `req` (or `request` — a Fetch Request, or
+ * `{ headers: await headers() }` in an RSC) so the site origin can be derived
+ * from the request when it isn't configured statically.
+ */
+declare const getSitemapEntries: (payload: Payload, options?: {
+  groups?: string[];
+  req?: PayloadRequest;
+  request?: {
+    headers?: Headers;
+    url?: null | string;
+  };
+}) => Promise<Record<string, SitemapEntry[]>>;
+//#endregion
+//#region src/core/invalidate.d.ts
+/**
+ * Manually invalidate cached sitemap groups — e.g. from a hook on a global that
+ * feeds the `routes` option. Invalidates every group when none are given.
+ */
+declare const invalidateSitemap: (payload: Payload, groups?: string[]) => Promise<void>;
+//#endregion
+//#region src/core/resolved.d.ts
+/** Reserved group name for entries from the `routes` option. */
+declare const ROUTES_GROUP = "_routes";
+/** Reads the resolved plugin config stashed on the Payload config by `sitemapPlugin`. */
+declare const getSitemapConfig: (config: SanitizedConfig) => ResolvedSitemapConfig;
+//#endregion
+//#region src/core/robots.d.ts
+type BuildRobotsArgs = {
+  /** Payload admin route, used for the default disallow list. @default '/admin' */
+  adminRoute?: string;
+  /** Payload API route, used for the default disallow list. @default '/api' */
+  apiRoute?: string;
+  options?: RobotsOptions;
+  /** Absolute sitemap URL(s) advertised in the output. */
+  sitemaps: string[];
+};
+declare const buildRobotsData: ({
+  adminRoute,
+  apiRoute,
+  options,
+  sitemaps
+}: BuildRobotsArgs) => RobotsData;
+declare const renderRobotsTxt: (data: RobotsData) => string;
+/**
+ * robots.txt for any delivery mechanism. Defaults come from the plugin config;
+ * `overrides` win field-by-field, and `transform` gets the final say. Pass
+ * `request` so the default sitemap URL can derive its origin from the incoming
+ * request when `siteUrl` isn't configured statically.
+ */
+declare const generateRobotsTxt: (configInput: Promise<SanitizedConfig> | SanitizedConfig, overrides?: {
+  request?: SiteUrlContext["request"];
+} & RobotsOptions) => Promise<string>;
+//#endregion
+//#region src/core/xml.d.ts
+declare const escapeXml: (value: string) => string;
+declare const buildUrlsetXml: (entries: SitemapEntry[], defaults?: {
+  changeFreq?: ChangeFrequency;
+  priority?: number;
+}) => string;
+declare const buildSitemapIndexXml: (items: Array<{
+  lastmod?: string;
+  loc: string;
+}>) => string;
+//#endregion
+//#region src/plugin.d.ts
+declare const sitemapPlugin: (pluginConfig: SitemapPluginConfig) => Plugin;
+//#endregion
+export { ChangeFrequency, InternalSitemapCollectionConfig, ROUTES_GROUP, ResolvedSitemapConfig, ResolvedSitemapEndpoints, RobotsData, RobotsOptions, RobotsRule, SITEMAP_CACHE_TAG, type SiteUrlContext, SitemapCache, SitemapCollectionConfig, SitemapCollections, SitemapEndpointAccess, SitemapEndpointsConfig, SitemapEntry, SitemapInvalidateArgs, SitemapPathArgs, SitemapPluginConfig, SitemapRoute, SitemapRoutesFn, buildRobotsData, buildSitemapIndexXml, buildUrlsetXml, chunkFileName, createMemoryCache, createNextTagsCache, escapeXml, finalizeEntries, formatLoc, generateRobotsTxt, getChunkEntries, getGroupEntries, getIndexItems, getSitemapConfig, getSitemapEntries, invalidateSitemap, matchChunkFile, noopCache, renderRobotsTxt, resolveSiteUrl, siteUrlFromRequest, sitemapCacheTag, sitemapPlugin };
+//# sourceMappingURL=index.d.ts.map