@djangocfg/nextjs 2.1.415 → 2.1.417

package/dist/sitemap/index.d.mts

@@ -56,11 +56,27 @@ interface CreateDjangoSitemapOptions {
     /** Feed (chunk) revalidate window in seconds. Default: 3600. */
     feedRevalidate?: number;
 }
+interface CreateSitemapIndexOptions {
+    /** Canonical site host, e.g. `https://vamcar.com`. Chunk URLs in the
+     *  index are emitted as `${host}/sitemap/<id>.xml`. */
+    host: string;
+    /** Django backend base URL. When omitted, the index lists only the
+     *  static chunk (mirrors `createDjangoSitemap` without `apiUrl`). */
+    apiUrl?: string;
+    /** Revalidate window in seconds for both the upstream `index/` fetch
+     *  and the emitted XML's `s-maxage`. Default: 600. */
+    indexRevalidate?: number;
+    /** Include the `static` chunk id at the top of the index. Turn off if
+     *  the app's `sitemap.ts` opts out of `staticRoutes`. Default: true. */
+    includeStatic?: boolean;
+}
 interface CreateRobotsOptions {
     host: string;
     /** Disallow patterns. Default: ['/account/', '/auth', '/api/']. */
     disallow?: string[];
-    /** Override sitemap URL. Default: `${host}/sitemap.xml`. */
+    /** Override sitemap URL. Default: `${host}/sitemap.xml`.
+     *  When using `createDjangoSitemap` + `createSitemapIndex`, pass
+     *  `${host}/sitemap_index.xml` — see `createSitemapIndex` JSDoc. */
     sitemap?: string;
 }
 
@@ -104,6 +120,57 @@ interface SitemapApi {
 }
 declare function createDjangoSitemap(opts: CreateDjangoSitemapOptions): SitemapApi;
 
+/**
+ * createSitemapIndex — Route Handler factory for the sitemap-index XML.
+ *
+ * Next.js's `generateSitemaps()` API ships chunks at `/sitemap/<id>.xml`
+ * but does NOT emit a single sitemap-index document. Without one,
+ * robots.txt + crawlers point at a 404 and never discover the chunks.
+ * This factory closes that gap: it returns a `GET` Route Handler that
+ * mints a `<sitemapindex>` XML listing every chunk the matching
+ * `createDjangoSitemap` would produce.
+ *
+ * Mount it at **`app/sitemap_index.xml/route.ts`** — NOT `sitemap.xml`.
+ * `app/sitemap.ts` (where `createDjangoSitemap` lives) already owns
+ * `/sitemap.xml` in Next.js's metadata routing, even when its output is
+ * fan-out via `generateSitemaps()` and the singular URL serves 404.
+ * Putting a route handler at `app/sitemap.xml/route.ts` throws at build
+ * time: *Conflicting route and metadata at /sitemap.xml*.
+ *
+ * Usage — the full pattern with the matching chunk + robots factories:
+ *
+ * ```ts
+ * // apps/<app>/app/sitemap.ts — chunks
+ * import { createDjangoSitemap } from '@djangocfg/nextjs/sitemap';
+ * const { generateSitemaps, sitemap } = createDjangoSitemap({ ... });
+ * export { generateSitemaps, sitemap as default };
+ *
+ * // apps/<app>/app/sitemap_index.xml/route.ts — the index
+ * import { createSitemapIndex } from '@djangocfg/nextjs/sitemap';
+ * export const { GET } = createSitemapIndex({
+ *   host: process.env.NEXT_PUBLIC_SITE_URL!,
+ *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+ * });
+ * export const revalidate = 600;
+ *
+ * // apps/<app>/app/robots.ts — point crawlers at the index URL above
+ * import { createRobots } from '@djangocfg/nextjs/sitemap';
+ * const host = process.env.NEXT_PUBLIC_SITE_URL!;
+ * export default createRobots({
+ *   host,
+ *   sitemap: `${host}/sitemap_index.xml`,
+ * });
+ * ```
+ *
+ * Keep `host` / `apiUrl` in sync with the same app's `app/sitemap.ts`
+ * — the index just enumerates the chunks the other file emits.
+ */
+
+interface SitemapIndexRoute {
+    GET: () => Promise<Response>;
+}
+declare function createSitemapIndex(opts: CreateSitemapIndexOptions): SitemapIndexRoute;
+
 /**
  * createRobots — factory for Next.js `app/robots.ts`.
  *
@@ -111,15 +178,27 @@ declare function createDjangoSitemap(opts: CreateDjangoSitemapOptions): SitemapA
  * defaults cover the common cases (auth, account, API surface) — override
  * per app if needed.
  *
+ * The `sitemap` default `${host}/sitemap.xml` only makes sense for the
+ * single-file case. When the app uses `createDjangoSitemap`
+ * (`generateSitemaps()` → chunked output) **plus** `createSitemapIndex`
+ * — the canonical pairing — pass an explicit
+ * `sitemap: \`${host}/sitemap_index.xml\`` to point crawlers at the
+ * index. The default `/sitemap.xml` will serve a 404 in that setup
+ * (Next.js reserves it for the metadata route but doesn't emit content
+ * there).
+ *
  * Usage:
  *
  * ```ts
  * // apps/<app>/app/robots.ts
  * import { createRobots } from '@djangocfg/nextjs/sitemap';
  *
+ * const host = process.env.NEXT_PUBLIC_SITE_URL!;
+ *
  * export default createRobots({
- *   host: process.env.NEXT_PUBLIC_SITE_URL!,
+ *   host,
  *   disallow: ['/account/', '/auth', '/api/', '/apix/'],
+ *   sitemap: `${host}/sitemap_index.xml`, // matches createSitemapIndex
  * });
  * ```
  */
@@ -152,4 +231,4 @@ declare function decodeChunkId(id: string): {
 declare function fetchSitemapIndex(apiUrl: string, revalidate: number): Promise<SitemapIndex>;
 declare function fetchSitemapFeed(apiUrl: string, source: string, cursor: string | null, revalidate: number): Promise<SitemapFeedPage>;
 
-export { type CreateDjangoSitemapOptions, type CreateRobotsOptions, type SitemapChunkInfo, type SitemapEntry, type SitemapFeedPage, type SitemapIndex, type SitemapSourceInfo, type StaticRoute, createDjangoSitemap, createRobots, decodeChunkId, encodeChunkId, fetchSitemapFeed, fetchSitemapIndex };
+export { type CreateDjangoSitemapOptions, type CreateRobotsOptions, type CreateSitemapIndexOptions, type SitemapChunkInfo, type SitemapEntry, type SitemapFeedPage, type SitemapIndex, type SitemapSourceInfo, type StaticRoute, createDjangoSitemap, createRobots, createSitemapIndex, decodeChunkId, encodeChunkId, fetchSitemapFeed, fetchSitemapIndex };

package/dist/sitemap/index.mjs

@@ -1,3 +1,8 @@
+// src/sitemap/constants.ts
+var STATIC_ID = "static";
+var DEFAULT_INDEX_REVALIDATE = 600;
+var DEFAULT_FEED_REVALIDATE = 3600;
+
 // src/sitemap/fetch.ts
 var EMPTY_INDEX = {
   sources: [],
@@ -58,9 +63,6 @@ function decodeChunkId(id) {
 }
 
 // src/sitemap/sitemap.ts
-var STATIC_ID = "static";
-var DEFAULT_INDEX_REVALIDATE = 600;
-var DEFAULT_FEED_REVALIDATE = 3600;
 function createDjangoSitemap(opts) {
   const {
     host,
@@ -104,6 +106,56 @@ function renderStatic(host, routes) {
   }));
 }
 
+// src/sitemap/index-route.ts
+function createSitemapIndex(opts) {
+  const {
+    host,
+    apiUrl,
+    indexRevalidate = DEFAULT_INDEX_REVALIDATE,
+    includeStatic = true
+  } = opts;
+  return {
+    async GET() {
+      const ids = includeStatic ? [STATIC_ID] : [];
+      if (apiUrl) {
+        const index = await fetchSitemapIndex(apiUrl, indexRevalidate);
+        for (const s of index.sources) {
+          for (const c of s.chunks) {
+            ids.push(encodeChunkId(s.name, c.cursor_to));
+          }
+        }
+      }
+      const lastmod = (/* @__PURE__ */ new Date()).toISOString();
+      const body = renderIndex(host, ids, lastmod);
+      return new Response(body, {
+        status: 200,
+        headers: {
+          "content-type": "application/xml; charset=utf-8",
+          // Mirror the per-chunk revalidate so a cached CDN edge expires
+          // at the same cadence as the index it points at.
+          "cache-control": `public, s-maxage=${indexRevalidate}, stale-while-revalidate=${indexRevalidate}`
+        }
+      });
+    }
+  };
+}
+function renderIndex(host, ids, lastmod) {
+  const lines = [];
+  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+  lines.push('<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">');
+  for (const id of ids) {
+    lines.push("  <sitemap>");
+    lines.push(`    <loc>${escapeXml(`${host}/sitemap/${id}.xml`)}</loc>`);
+    lines.push(`    <lastmod>${lastmod}</lastmod>`);
+    lines.push("  </sitemap>");
+  }
+  lines.push("</sitemapindex>");
+  return lines.join("\n");
+}
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
 // src/sitemap/robots.ts
 var DEFAULT_DISALLOW = ["/account/", "/auth", "/api/"];
 function createRobots(opts) {
@@ -117,6 +169,7 @@ function createRobots(opts) {
 export {
   createDjangoSitemap,
   createRobots,
+  createSitemapIndex,
   decodeChunkId,
   encodeChunkId,
   fetchSitemapFeed,

package/dist/sitemap/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/sitemap/fetch.ts","../../src/sitemap/ids.ts","../../src/sitemap/sitemap.ts","../../src/sitemap/robots.ts"],"sourcesContent":["/**\n * Sitemap fetch helpers — never throw.\n *\n * Failures are converted to empty payloads so a transient Django outage\n * doesn't break `next build`. The next ISR cycle (`revalidate`) recovers\n * automatically.\n */\n\nimport type { SitemapFeedPage, SitemapIndex } from './types';\n\nconst EMPTY_INDEX: SitemapIndex = {\n  sources: [],\n  generated_at: new Date(0).toISOString(),\n  ttl_seconds: 60,\n};\n\nconst emptyFeed = (source: string, cursor: string | null): SitemapFeedPage => ({\n  source,\n  chunk_id: `${source}-empty`,\n  count: 0,\n  has_more: false,\n  next_cursor: cursor,\n  entries: [],\n});\n\nexport async function fetchSitemapIndex(\n  apiUrl: string,\n  revalidate: number,\n): Promise<SitemapIndex> {\n  try {\n    const r = await fetch(`${apiUrl}/cfg/sitemap/index/`, {\n      next: { revalidate },\n    });\n    if (!r.ok) {\n      console.warn(`[sitemap] index fetch returned ${r.status}; falling back to empty`);\n      return EMPTY_INDEX;\n    }\n    return (await r.json()) as SitemapIndex;\n  } catch (err) {\n    console.warn('[sitemap] index fetch failed:', err);\n    return EMPTY_INDEX;\n  }\n}\n\nexport async function fetchSitemapFeed(\n  apiUrl: string,\n  source: string,\n  cursor: string | null,\n  revalidate: number,\n): Promise<SitemapFeedPage> {\n  const params = new URLSearchParams({ source });\n  if (cursor) params.set('cursor', cursor);\n  try {\n    const r = await fetch(`${apiUrl}/cfg/sitemap/feed/?${params}`, {\n      next: { revalidate },\n    });\n    if (!r.ok) {\n      console.warn(`[sitemap] feed ${source} returned ${r.status}; falling back to empty`);\n      return emptyFeed(source, cursor);\n    }\n    return (await r.json()) as SitemapFeedPage;\n  } catch (err) {\n    console.warn(`[sitemap] feed ${source} fetch failed:`, err);\n    return emptyFeed(source, cursor);\n  }\n}\n","/**\n * Sitemap chunk id encoding.\n *\n * Each Next.js sitemap file is addressed by an opaque string id. We\n * round-trip a `(source, cursor)` pair through that id so the default\n * sitemap handler knows which Django chunk to fetch.\n *\n * Separator `--` is unambiguous: backend cursors use URL-safe base64 (`-_`).\n */\n\nexport function encodeChunkId(source: string, cursor: string | null): string {\n  return `${source}--${cursor ?? ''}`;\n}\n\nexport function decodeChunkId(id: string): { source: string; cursor: string | null } {\n  const sep = id.indexOf('--');\n  if (sep === -1) return { source: id, cursor: null };\n  const source = id.slice(0, sep);\n  const cursorRaw = id.slice(sep + 2);\n  return { source, cursor: cursorRaw === '' ? null : cursorRaw };\n}\n","/**\n * createDjangoSitemap — factory for Next.js `app/sitemap.ts`.\n *\n * Backed by `django_cfg.modules.django_sitemap`: the backend exposes a\n * paginated JSON feed, this factory turns each chunk into a Next.js\n * sitemap file via `generateSitemaps()`.\n *\n * Usage:\n *\n * ```ts\n * // apps/<app>/app/sitemap.ts\n * import { createDjangoSitemap } from '@djangocfg/nextjs/sitemap';\n *\n * const { generateSitemaps, sitemap } = createDjangoSitemap({\n *   host: process.env.NEXT_PUBLIC_SITE_URL!,\n *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,\n *   staticRoutes: [\n *     { path: '/', changeFrequency: 'daily', priority: 1.0 },\n *     { path: '/catalog', changeFrequency: 'daily', priority: 0.9 },\n *   ],\n * });\n *\n * export { generateSitemaps, sitemap as default };\n * export const revalidate = 3600;\n * ```\n *\n * Without `apiUrl`, the sitemap emits only the static routes — handy for\n * marketing sites that don't have a backend-driven URL space.\n */\n\nimport type { MetadataRoute } from 'next';\n\nimport { fetchSitemapFeed, fetchSitemapIndex } from './fetch';\nimport { decodeChunkId, encodeChunkId } from './ids';\n\nimport type { CreateDjangoSitemapOptions, StaticRoute } from './types';\n\nconst STATIC_ID = 'static';\nconst DEFAULT_INDEX_REVALIDATE = 600;\nconst DEFAULT_FEED_REVALIDATE = 3600;\n\ninterface SitemapApi {\n  generateSitemaps: () => Promise<Array<{ id: string }>>;\n  sitemap: (props: { id: Promise<string> }) => Promise<MetadataRoute.Sitemap>;\n}\n\nexport function createDjangoSitemap(opts: CreateDjangoSitemapOptions): SitemapApi {\n  const {\n    host,\n    apiUrl,\n    staticRoutes = [],\n    indexRevalidate = DEFAULT_INDEX_REVALIDATE,\n    feedRevalidate = DEFAULT_FEED_REVALIDATE,\n  } = opts;\n\n  return {\n    async generateSitemaps() {\n      const ids: Array<{ id: string }> = [{ id: STATIC_ID }];\n      if (!apiUrl) return ids;\n      const index = await fetchSitemapIndex(apiUrl, indexRevalidate);\n      for (const s of index.sources) {\n        for (const c of s.chunks) {\n          ids.push({ id: encodeChunkId(s.name, c.cursor_to) });\n        }\n      }\n      return ids;\n    },\n\n    async sitemap({ id: idPromise }) {\n      const id = await idPromise;\n\n      if (id === STATIC_ID) {\n        return renderStatic(host, staticRoutes);\n      }\n\n      if (!apiUrl) return [];\n\n      const { source, cursor } = decodeChunkId(id);\n      const feed = await fetchSitemapFeed(apiUrl, source, cursor, feedRevalidate);\n      return feed.entries.map((e) => ({\n        url: `${host}${e.loc}`,\n        lastModified: e.lastmod ? new Date(e.lastmod) : undefined,\n      }));\n    },\n  };\n}\n\nfunction renderStatic(host: string, routes: StaticRoute[]): MetadataRoute.Sitemap {\n  return routes.map((r) => ({\n    url: `${host}${r.path}`,\n    changeFrequency: r.changeFrequency,\n    priority: r.priority,\n  }));\n}\n","/**\n * createRobots — factory for Next.js `app/robots.ts`.\n *\n * Emits a single `User-Agent: *` block plus a Sitemap pointer. Disallow\n * defaults cover the common cases (auth, account, API surface) — override\n * per app if needed.\n *\n * Usage:\n *\n * ```ts\n * // apps/<app>/app/robots.ts\n * import { createRobots } from '@djangocfg/nextjs/sitemap';\n *\n * export default createRobots({\n *   host: process.env.NEXT_PUBLIC_SITE_URL!,\n *   disallow: ['/account/', '/auth', '/api/', '/apix/'],\n * });\n * ```\n */\n\nimport type { MetadataRoute } from 'next';\n\nimport type { CreateRobotsOptions } from './types';\n\nconst DEFAULT_DISALLOW = ['/account/', '/auth', '/api/'];\n\nexport function createRobots(opts: CreateRobotsOptions): () => MetadataRoute.Robots {\n  const { host, disallow = DEFAULT_DISALLOW, sitemap } = opts;\n  return () => ({\n    rules: [{ userAgent: '*', allow: '/', disallow }],\n    sitemap: sitemap ?? `${host}/sitemap.xml`,\n    host,\n  });\n}\n"],"mappings":";AAUA,IAAM,cAA4B;AAAA,EAChC,SAAS,CAAC;AAAA,EACV,eAAc,oBAAI,KAAK,CAAC,GAAE,YAAY;AAAA,EACtC,aAAa;AACf;AAEA,IAAM,YAAY,CAAC,QAAgB,YAA4C;AAAA,EAC7E;AAAA,EACA,UAAU,GAAG,MAAM;AAAA,EACnB,OAAO;AAAA,EACP,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AACZ;AAEA,eAAsB,kBACpB,QACA,YACuB;AACvB,MAAI;AACF,UAAM,IAAI,MAAM,MAAM,GAAG,MAAM,uBAAuB;AAAA,MACpD,MAAM,EAAE,WAAW;AAAA,IACrB,CAAC;AACD,QAAI,CAAC,EAAE,IAAI;AACT,cAAQ,KAAK,kCAAkC,EAAE,MAAM,yBAAyB;AAChF,aAAO;AAAA,IACT;AACA,WAAQ,MAAM,EAAE,KAAK;AAAA,EACvB,SAAS,KAAK;AACZ,YAAQ,KAAK,iCAAiC,GAAG;AACjD,WAAO;AAAA,EACT;AACF;AAEA,eAAsB,iBACpB,QACA,QACA,QACA,YAC0B;AAC1B,QAAM,SAAS,IAAI,gBAAgB,EAAE,OAAO,CAAC;AAC7C,MAAI,OAAQ,QAAO,IAAI,UAAU,MAAM;AACvC,MAAI;AACF,UAAM,IAAI,MAAM,MAAM,GAAG,MAAM,sBAAsB,MAAM,IAAI;AAAA,MAC7D,MAAM,EAAE,WAAW;AAAA,IACrB,CAAC;AACD,QAAI,CAAC,EAAE,IAAI;AACT,cAAQ,KAAK,kBAAkB,MAAM,aAAa,EAAE,MAAM,yBAAyB;AACnF,aAAO,UAAU,QAAQ,MAAM;AAAA,IACjC;AACA,WAAQ,MAAM,EAAE,KAAK;AAAA,EACvB,SAAS,KAAK;AACZ,YAAQ,KAAK,kBAAkB,MAAM,kBAAkB,GAAG;AAC1D,WAAO,UAAU,QAAQ,MAAM;AAAA,EACjC;AACF;;;ACvDO,SAAS,cAAc,QAAgB,QAA+B;AAC3E,SAAO,GAAG,MAAM,KAAK,UAAU,EAAE;AACnC;AAEO,SAAS,cAAc,IAAuD;AACnF,QAAM,MAAM,GAAG,QAAQ,IAAI;AAC3B,MAAI,QAAQ,GAAI,QAAO,EAAE,QAAQ,IAAI,QAAQ,KAAK;AAClD,QAAM,SAAS,GAAG,MAAM,GAAG,GAAG;AAC9B,QAAM,YAAY,GAAG,MAAM,MAAM,CAAC;AAClC,SAAO,EAAE,QAAQ,QAAQ,cAAc,KAAK,OAAO,UAAU;AAC/D;;;ACiBA,IAAM,YAAY;AAClB,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;AAOzB,SAAS,oBAAoB,MAA8C;AAChF,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,eAAe,CAAC;AAAA,IAChB,kBAAkB;AAAA,IAClB,iBAAiB;AAAA,EACnB,IAAI;AAEJ,SAAO;AAAA,IACL,MAAM,mBAAmB;AACvB,YAAM,MAA6B,CAAC,EAAE,IAAI,UAAU,CAAC;AACrD,UAAI,CAAC,OAAQ,QAAO;AACpB,YAAM,QAAQ,MAAM,kBAAkB,QAAQ,eAAe;AAC7D,iBAAW,KAAK,MAAM,SAAS;AAC7B,mBAAW,KAAK,EAAE,QAAQ;AACxB,cAAI,KAAK,EAAE,IAAI,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAAA,QACrD;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,QAAQ,EAAE,IAAI,UAAU,GAAG;AAC/B,YAAM,KAAK,MAAM;AAEjB,UAAI,OAAO,WAAW;AACpB,eAAO,aAAa,MAAM,YAAY;AAAA,MACxC;AAEA,UAAI,CAAC,OAAQ,QAAO,CAAC;AAErB,YAAM,EAAE,QAAQ,OAAO,IAAI,cAAc,EAAE;AAC3C,YAAM,OAAO,MAAM,iBAAiB,QAAQ,QAAQ,QAAQ,cAAc;AAC1E,aAAO,KAAK,QAAQ,IAAI,CAAC,OAAO;AAAA,QAC9B,KAAK,GAAG,IAAI,GAAG,EAAE,GAAG;AAAA,QACpB,cAAc,EAAE,UAAU,IAAI,KAAK,EAAE,OAAO,IAAI;AAAA,MAClD,EAAE;AAAA,IACJ;AAAA,EACF;AACF;AAEA,SAAS,aAAa,MAAc,QAA8C;AAChF,SAAO,OAAO,IAAI,CAAC,OAAO;AAAA,IACxB,KAAK,GAAG,IAAI,GAAG,EAAE,IAAI;AAAA,IACrB,iBAAiB,EAAE;AAAA,IACnB,UAAU,EAAE;AAAA,EACd,EAAE;AACJ;;;ACrEA,IAAM,mBAAmB,CAAC,aAAa,SAAS,OAAO;AAEhD,SAAS,aAAa,MAAuD;AAClF,QAAM,EAAE,MAAM,WAAW,kBAAkB,QAAQ,IAAI;AACvD,SAAO,OAAO;AAAA,IACZ,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,KAAK,SAAS,CAAC;AAAA,IAChD,SAAS,WAAW,GAAG,IAAI;AAAA,IAC3B;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/sitemap/constants.ts","../../src/sitemap/fetch.ts","../../src/sitemap/ids.ts","../../src/sitemap/sitemap.ts","../../src/sitemap/index-route.ts","../../src/sitemap/robots.ts"],"sourcesContent":["/**\n * Shared sitemap constants.\n *\n * Pulled out so both the chunk factory (`createDjangoSitemap`) and the\n * index Route Handler (`createSitemapIndex`) agree on the id of the\n * frontend-only static-routes chunk.\n */\n\nexport const STATIC_ID = 'static';\nexport const DEFAULT_INDEX_REVALIDATE = 600;\nexport const DEFAULT_FEED_REVALIDATE = 3600;\n","/**\n * Sitemap fetch helpers — never throw.\n *\n * Failures are converted to empty payloads so a transient Django outage\n * doesn't break `next build`. The next ISR cycle (`revalidate`) recovers\n * automatically.\n */\n\nimport type { SitemapFeedPage, SitemapIndex } from './types';\n\nconst EMPTY_INDEX: SitemapIndex = {\n  sources: [],\n  generated_at: new Date(0).toISOString(),\n  ttl_seconds: 60,\n};\n\nconst emptyFeed = (source: string, cursor: string | null): SitemapFeedPage => ({\n  source,\n  chunk_id: `${source}-empty`,\n  count: 0,\n  has_more: false,\n  next_cursor: cursor,\n  entries: [],\n});\n\nexport async function fetchSitemapIndex(\n  apiUrl: string,\n  revalidate: number,\n): Promise<SitemapIndex> {\n  try {\n    const r = await fetch(`${apiUrl}/cfg/sitemap/index/`, {\n      next: { revalidate },\n    });\n    if (!r.ok) {\n      console.warn(`[sitemap] index fetch returned ${r.status}; falling back to empty`);\n      return EMPTY_INDEX;\n    }\n    return (await r.json()) as SitemapIndex;\n  } catch (err) {\n    console.warn('[sitemap] index fetch failed:', err);\n    return EMPTY_INDEX;\n  }\n}\n\nexport async function fetchSitemapFeed(\n  apiUrl: string,\n  source: string,\n  cursor: string | null,\n  revalidate: number,\n): Promise<SitemapFeedPage> {\n  const params = new URLSearchParams({ source });\n  if (cursor) params.set('cursor', cursor);\n  try {\n    const r = await fetch(`${apiUrl}/cfg/sitemap/feed/?${params}`, {\n      next: { revalidate },\n    });\n    if (!r.ok) {\n      console.warn(`[sitemap] feed ${source} returned ${r.status}; falling back to empty`);\n      return emptyFeed(source, cursor);\n    }\n    return (await r.json()) as SitemapFeedPage;\n  } catch (err) {\n    console.warn(`[sitemap] feed ${source} fetch failed:`, err);\n    return emptyFeed(source, cursor);\n  }\n}\n","/**\n * Sitemap chunk id encoding.\n *\n * Each Next.js sitemap file is addressed by an opaque string id. We\n * round-trip a `(source, cursor)` pair through that id so the default\n * sitemap handler knows which Django chunk to fetch.\n *\n * Separator `--` is unambiguous: backend cursors use URL-safe base64 (`-_`).\n */\n\nexport function encodeChunkId(source: string, cursor: string | null): string {\n  return `${source}--${cursor ?? ''}`;\n}\n\nexport function decodeChunkId(id: string): { source: string; cursor: string | null } {\n  const sep = id.indexOf('--');\n  if (sep === -1) return { source: id, cursor: null };\n  const source = id.slice(0, sep);\n  const cursorRaw = id.slice(sep + 2);\n  return { source, cursor: cursorRaw === '' ? null : cursorRaw };\n}\n","/**\n * createDjangoSitemap — factory for Next.js `app/sitemap.ts`.\n *\n * Backed by `django_cfg.modules.django_sitemap`: the backend exposes a\n * paginated JSON feed, this factory turns each chunk into a Next.js\n * sitemap file via `generateSitemaps()`.\n *\n * Usage:\n *\n * ```ts\n * // apps/<app>/app/sitemap.ts\n * import { createDjangoSitemap } from '@djangocfg/nextjs/sitemap';\n *\n * const { generateSitemaps, sitemap } = createDjangoSitemap({\n *   host: process.env.NEXT_PUBLIC_SITE_URL!,\n *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,\n *   staticRoutes: [\n *     { path: '/', changeFrequency: 'daily', priority: 1.0 },\n *     { path: '/catalog', changeFrequency: 'daily', priority: 0.9 },\n *   ],\n * });\n *\n * export { generateSitemaps, sitemap as default };\n * export const revalidate = 3600;\n * ```\n *\n * Without `apiUrl`, the sitemap emits only the static routes — handy for\n * marketing sites that don't have a backend-driven URL space.\n */\n\nimport type { MetadataRoute } from 'next';\n\nimport {\n  DEFAULT_FEED_REVALIDATE,\n  DEFAULT_INDEX_REVALIDATE,\n  STATIC_ID,\n} from './constants';\nimport { fetchSitemapFeed, fetchSitemapIndex } from './fetch';\nimport { decodeChunkId, encodeChunkId } from './ids';\n\nimport type { CreateDjangoSitemapOptions, StaticRoute } from './types';\n\ninterface SitemapApi {\n  generateSitemaps: () => Promise<Array<{ id: string }>>;\n  sitemap: (props: { id: Promise<string> }) => Promise<MetadataRoute.Sitemap>;\n}\n\nexport function createDjangoSitemap(opts: CreateDjangoSitemapOptions): SitemapApi {\n  const {\n    host,\n    apiUrl,\n    staticRoutes = [],\n    indexRevalidate = DEFAULT_INDEX_REVALIDATE,\n    feedRevalidate = DEFAULT_FEED_REVALIDATE,\n  } = opts;\n\n  return {\n    async generateSitemaps() {\n      const ids: Array<{ id: string }> = [{ id: STATIC_ID }];\n      if (!apiUrl) return ids;\n      const index = await fetchSitemapIndex(apiUrl, indexRevalidate);\n      for (const s of index.sources) {\n        for (const c of s.chunks) {\n          ids.push({ id: encodeChunkId(s.name, c.cursor_to) });\n        }\n      }\n      return ids;\n    },\n\n    async sitemap({ id: idPromise }) {\n      const id = await idPromise;\n\n      if (id === STATIC_ID) {\n        return renderStatic(host, staticRoutes);\n      }\n\n      if (!apiUrl) return [];\n\n      const { source, cursor } = decodeChunkId(id);\n      const feed = await fetchSitemapFeed(apiUrl, source, cursor, feedRevalidate);\n      return feed.entries.map((e) => ({\n        url: `${host}${e.loc}`,\n        lastModified: e.lastmod ? new Date(e.lastmod) : undefined,\n      }));\n    },\n  };\n}\n\nfunction renderStatic(host: string, routes: StaticRoute[]): MetadataRoute.Sitemap {\n  return routes.map((r) => ({\n    url: `${host}${r.path}`,\n    changeFrequency: r.changeFrequency,\n    priority: r.priority,\n  }));\n}\n","/**\n * createSitemapIndex — Route Handler factory for the sitemap-index XML.\n *\n * Next.js's `generateSitemaps()` API ships chunks at `/sitemap/<id>.xml`\n * but does NOT emit a single sitemap-index document. Without one,\n * robots.txt + crawlers point at a 404 and never discover the chunks.\n * This factory closes that gap: it returns a `GET` Route Handler that\n * mints a `<sitemapindex>` XML listing every chunk the matching\n * `createDjangoSitemap` would produce.\n *\n * Mount it at **`app/sitemap_index.xml/route.ts`** — NOT `sitemap.xml`.\n * `app/sitemap.ts` (where `createDjangoSitemap` lives) already owns\n * `/sitemap.xml` in Next.js's metadata routing, even when its output is\n * fan-out via `generateSitemaps()` and the singular URL serves 404.\n * Putting a route handler at `app/sitemap.xml/route.ts` throws at build\n * time: *Conflicting route and metadata at /sitemap.xml*.\n *\n * Usage — the full pattern with the matching chunk + robots factories:\n *\n * ```ts\n * // apps/<app>/app/sitemap.ts — chunks\n * import { createDjangoSitemap } from '@djangocfg/nextjs/sitemap';\n * const { generateSitemaps, sitemap } = createDjangoSitemap({ ... });\n * export { generateSitemaps, sitemap as default };\n *\n * // apps/<app>/app/sitemap_index.xml/route.ts — the index\n * import { createSitemapIndex } from '@djangocfg/nextjs/sitemap';\n * export const { GET } = createSitemapIndex({\n *   host: process.env.NEXT_PUBLIC_SITE_URL!,\n *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,\n * });\n * export const revalidate = 600;\n *\n * // apps/<app>/app/robots.ts — point crawlers at the index URL above\n * import { createRobots } from '@djangocfg/nextjs/sitemap';\n * const host = process.env.NEXT_PUBLIC_SITE_URL!;\n * export default createRobots({\n *   host,\n *   sitemap: `${host}/sitemap_index.xml`,\n * });\n * ```\n *\n * Keep `host` / `apiUrl` in sync with the same app's `app/sitemap.ts`\n * — the index just enumerates the chunks the other file emits.\n */\n\nimport {\n  DEFAULT_INDEX_REVALIDATE,\n  STATIC_ID,\n} from './constants';\nimport { fetchSitemapIndex } from './fetch';\nimport { encodeChunkId } from './ids';\n\nimport type { CreateSitemapIndexOptions } from './types';\n\ninterface SitemapIndexRoute {\n  GET: () => Promise<Response>;\n}\n\nexport function createSitemapIndex(opts: CreateSitemapIndexOptions): SitemapIndexRoute {\n  const {\n    host,\n    apiUrl,\n    indexRevalidate = DEFAULT_INDEX_REVALIDATE,\n    includeStatic = true,\n  } = opts;\n\n  return {\n    async GET() {\n      const ids: string[] = includeStatic ? [STATIC_ID] : [];\n\n      if (apiUrl) {\n        const index = await fetchSitemapIndex(apiUrl, indexRevalidate);\n        for (const s of index.sources) {\n          for (const c of s.chunks) {\n            ids.push(encodeChunkId(s.name, c.cursor_to));\n          }\n        }\n      }\n\n      const lastmod = new Date().toISOString();\n      const body = renderIndex(host, ids, lastmod);\n\n      return new Response(body, {\n        status: 200,\n        headers: {\n          'content-type': 'application/xml; charset=utf-8',\n          // Mirror the per-chunk revalidate so a cached CDN edge expires\n          // at the same cadence as the index it points at.\n          'cache-control': `public, s-maxage=${indexRevalidate}, stale-while-revalidate=${indexRevalidate}`,\n        },\n      });\n    },\n  };\n}\n\nfunction renderIndex(host: string, ids: string[], lastmod: string): string {\n  const lines: string[] = [];\n  lines.push('<?xml version=\"1.0\" encoding=\"UTF-8\"?>');\n  lines.push('<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">');\n  for (const id of ids) {\n    lines.push('  <sitemap>');\n    lines.push(`    <loc>${escapeXml(`${host}/sitemap/${id}.xml`)}</loc>`);\n    lines.push(`    <lastmod>${lastmod}</lastmod>`);\n    lines.push('  </sitemap>');\n  }\n  lines.push('</sitemapindex>');\n  return lines.join('\\n');\n}\n\nfunction escapeXml(s: string): string {\n  return s\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&apos;');\n}\n","/**\n * createRobots — factory for Next.js `app/robots.ts`.\n *\n * Emits a single `User-Agent: *` block plus a Sitemap pointer. Disallow\n * defaults cover the common cases (auth, account, API surface) — override\n * per app if needed.\n *\n * The `sitemap` default `${host}/sitemap.xml` only makes sense for the\n * single-file case. When the app uses `createDjangoSitemap`\n * (`generateSitemaps()` → chunked output) **plus** `createSitemapIndex`\n * — the canonical pairing — pass an explicit\n * `sitemap: \\`${host}/sitemap_index.xml\\`` to point crawlers at the\n * index. The default `/sitemap.xml` will serve a 404 in that setup\n * (Next.js reserves it for the metadata route but doesn't emit content\n * there).\n *\n * Usage:\n *\n * ```ts\n * // apps/<app>/app/robots.ts\n * import { createRobots } from '@djangocfg/nextjs/sitemap';\n *\n * const host = process.env.NEXT_PUBLIC_SITE_URL!;\n *\n * export default createRobots({\n *   host,\n *   disallow: ['/account/', '/auth', '/api/', '/apix/'],\n *   sitemap: `${host}/sitemap_index.xml`, // matches createSitemapIndex\n * });\n * ```\n */\n\nimport type { MetadataRoute } from 'next';\n\nimport type { CreateRobotsOptions } from './types';\n\nconst DEFAULT_DISALLOW = ['/account/', '/auth', '/api/'];\n\nexport function createRobots(opts: CreateRobotsOptions): () => MetadataRoute.Robots {\n  const { host, disallow = DEFAULT_DISALLOW, sitemap } = opts;\n  return () => ({\n    rules: [{ userAgent: '*', allow: '/', disallow }],\n    sitemap: sitemap ?? `${host}/sitemap.xml`,\n    host,\n  });\n}\n"],"mappings":";AAQO,IAAM,YAAY;AAClB,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;;;ACAvC,IAAM,cAA4B;AAAA,EAChC,SAAS,CAAC;AAAA,EACV,eAAc,oBAAI,KAAK,CAAC,GAAE,YAAY;AAAA,EACtC,aAAa;AACf;AAEA,IAAM,YAAY,CAAC,QAAgB,YAA4C;AAAA,EAC7E;AAAA,EACA,UAAU,GAAG,MAAM;AAAA,EACnB,OAAO;AAAA,EACP,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AACZ;AAEA,eAAsB,kBACpB,QACA,YACuB;AACvB,MAAI;AACF,UAAM,IAAI,MAAM,MAAM,GAAG,MAAM,uBAAuB;AAAA,MACpD,MAAM,EAAE,WAAW;AAAA,IACrB,CAAC;AACD,QAAI,CAAC,EAAE,IAAI;AACT,cAAQ,KAAK,kCAAkC,EAAE,MAAM,yBAAyB;AAChF,aAAO;AAAA,IACT;AACA,WAAQ,MAAM,EAAE,KAAK;AAAA,EACvB,SAAS,KAAK;AACZ,YAAQ,KAAK,iCAAiC,GAAG;AACjD,WAAO;AAAA,EACT;AACF;AAEA,eAAsB,iBACpB,QACA,QACA,QACA,YAC0B;AAC1B,QAAM,SAAS,IAAI,gBAAgB,EAAE,OAAO,CAAC;AAC7C,MAAI,OAAQ,QAAO,IAAI,UAAU,MAAM;AACvC,MAAI;AACF,UAAM,IAAI,MAAM,MAAM,GAAG,MAAM,sBAAsB,MAAM,IAAI;AAAA,MAC7D,MAAM,EAAE,WAAW;AAAA,IACrB,CAAC;AACD,QAAI,CAAC,EAAE,IAAI;AACT,cAAQ,KAAK,kBAAkB,MAAM,aAAa,EAAE,MAAM,yBAAyB;AACnF,aAAO,UAAU,QAAQ,MAAM;AAAA,IACjC;AACA,WAAQ,MAAM,EAAE,KAAK;AAAA,EACvB,SAAS,KAAK;AACZ,YAAQ,KAAK,kBAAkB,MAAM,kBAAkB,GAAG;AAC1D,WAAO,UAAU,QAAQ,MAAM;AAAA,EACjC;AACF;;;ACvDO,SAAS,cAAc,QAAgB,QAA+B;AAC3E,SAAO,GAAG,MAAM,KAAK,UAAU,EAAE;AACnC;AAEO,SAAS,cAAc,IAAuD;AACnF,QAAM,MAAM,GAAG,QAAQ,IAAI;AAC3B,MAAI,QAAQ,GAAI,QAAO,EAAE,QAAQ,IAAI,QAAQ,KAAK;AAClD,QAAM,SAAS,GAAG,MAAM,GAAG,GAAG;AAC9B,QAAM,YAAY,GAAG,MAAM,MAAM,CAAC;AAClC,SAAO,EAAE,QAAQ,QAAQ,cAAc,KAAK,OAAO,UAAU;AAC/D;;;AC2BO,SAAS,oBAAoB,MAA8C;AAChF,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,eAAe,CAAC;AAAA,IAChB,kBAAkB;AAAA,IAClB,iBAAiB;AAAA,EACnB,IAAI;AAEJ,SAAO;AAAA,IACL,MAAM,mBAAmB;AACvB,YAAM,MAA6B,CAAC,EAAE,IAAI,UAAU,CAAC;AACrD,UAAI,CAAC,OAAQ,QAAO;AACpB,YAAM,QAAQ,MAAM,kBAAkB,QAAQ,eAAe;AAC7D,iBAAW,KAAK,MAAM,SAAS;AAC7B,mBAAW,KAAK,EAAE,QAAQ;AACxB,cAAI,KAAK,EAAE,IAAI,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAAA,QACrD;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,QAAQ,EAAE,IAAI,UAAU,GAAG;AAC/B,YAAM,KAAK,MAAM;AAEjB,UAAI,OAAO,WAAW;AACpB,eAAO,aAAa,MAAM,YAAY;AAAA,MACxC;AAEA,UAAI,CAAC,OAAQ,QAAO,CAAC;AAErB,YAAM,EAAE,QAAQ,OAAO,IAAI,cAAc,EAAE;AAC3C,YAAM,OAAO,MAAM,iBAAiB,QAAQ,QAAQ,QAAQ,cAAc;AAC1E,aAAO,KAAK,QAAQ,IAAI,CAAC,OAAO;AAAA,QAC9B,KAAK,GAAG,IAAI,GAAG,EAAE,GAAG;AAAA,QACpB,cAAc,EAAE,UAAU,IAAI,KAAK,EAAE,OAAO,IAAI;AAAA,MAClD,EAAE;AAAA,IACJ;AAAA,EACF;AACF;AAEA,SAAS,aAAa,MAAc,QAA8C;AAChF,SAAO,OAAO,IAAI,CAAC,OAAO;AAAA,IACxB,KAAK,GAAG,IAAI,GAAG,EAAE,IAAI;AAAA,IACrB,iBAAiB,EAAE;AAAA,IACnB,UAAU,EAAE;AAAA,EACd,EAAE;AACJ;;;ACnCO,SAAS,mBAAmB,MAAoD;AACrF,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,kBAAkB;AAAA,IAClB,gBAAgB;AAAA,EAClB,IAAI;AAEJ,SAAO;AAAA,IACL,MAAM,MAAM;AACV,YAAM,MAAgB,gBAAgB,CAAC,SAAS,IAAI,CAAC;AAErD,UAAI,QAAQ;AACV,cAAM,QAAQ,MAAM,kBAAkB,QAAQ,eAAe;AAC7D,mBAAW,KAAK,MAAM,SAAS;AAC7B,qBAAW,KAAK,EAAE,QAAQ;AACxB,gBAAI,KAAK,cAAc,EAAE,MAAM,EAAE,SAAS,CAAC;AAAA,UAC7C;AAAA,QACF;AAAA,MACF;AAEA,YAAM,WAAU,oBAAI,KAAK,GAAE,YAAY;AACvC,YAAM,OAAO,YAAY,MAAM,KAAK,OAAO;AAE3C,aAAO,IAAI,SAAS,MAAM;AAAA,QACxB,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,gBAAgB;AAAA;AAAA;AAAA,UAGhB,iBAAiB,oBAAoB,eAAe,4BAA4B,eAAe;AAAA,QACjG;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEA,SAAS,YAAY,MAAc,KAAe,SAAyB;AACzE,QAAM,QAAkB,CAAC;AACzB,QAAM,KAAK,wCAAwC;AACnD,QAAM,KAAK,oEAAoE;AAC/E,aAAW,MAAM,KAAK;AACpB,UAAM,KAAK,aAAa;AACxB,UAAM,KAAK,YAAY,UAAU,GAAG,IAAI,YAAY,EAAE,MAAM,CAAC,QAAQ;AACrE,UAAM,KAAK,gBAAgB,OAAO,YAAY;AAC9C,UAAM,KAAK,cAAc;AAAA,EAC3B;AACA,QAAM,KAAK,iBAAiB;AAC5B,SAAO,MAAM,KAAK,IAAI;AACxB;AAEA,SAAS,UAAU,GAAmB;AACpC,SAAO,EACJ,QAAQ,MAAM,OAAO,EACrB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,QAAQ,EACtB,QAAQ,MAAM,QAAQ;AAC3B;;;ACjFA,IAAM,mBAAmB,CAAC,aAAa,SAAS,OAAO;AAEhD,SAAS,aAAa,MAAuD;AAClF,QAAM,EAAE,MAAM,WAAW,kBAAkB,QAAQ,IAAI;AACvD,SAAO,OAAO;AAAA,IACZ,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,KAAK,SAAS,CAAC;AAAA,IAChD,SAAS,WAAW,GAAG,IAAI;AAAA,IAC3B;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.415",
+  "version": "2.1.417",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -143,9 +143,9 @@
     "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.415",
-    "@djangocfg/monitor": "^2.1.415",
-    "@djangocfg/ui-core": "^2.1.415",
+    "@djangocfg/i18n": "^2.1.417",
+    "@djangocfg/monitor": "^2.1.417",
+    "@djangocfg/ui-core": "^2.1.417",
     "next": "^16.2.2"
   },
   "peerDependenciesMeta": {
@@ -167,11 +167,11 @@
     "serwist": "^9.2.3"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.415",
-    "@djangocfg/monitor": "^2.1.415",
-    "@djangocfg/ui-core": "^2.1.415",
-    "@djangocfg/layouts": "^2.1.415",
-    "@djangocfg/typescript-config": "^2.1.415",
+    "@djangocfg/i18n": "^2.1.417",
+    "@djangocfg/monitor": "^2.1.417",
+    "@djangocfg/ui-core": "^2.1.417",
+    "@djangocfg/layouts": "^2.1.417",
+    "@djangocfg/typescript-config": "^2.1.417",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/sitemap/constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared sitemap constants.
+ *
+ * Pulled out so both the chunk factory (`createDjangoSitemap`) and the
+ * index Route Handler (`createSitemapIndex`) agree on the id of the
+ * frontend-only static-routes chunk.
+ */
+
+export const STATIC_ID = 'static';
+export const DEFAULT_INDEX_REVALIDATE = 600;
+export const DEFAULT_FEED_REVALIDATE = 3600;

package/src/sitemap/index-route.ts

@@ -0,0 +1,118 @@
+/**
+ * createSitemapIndex — Route Handler factory for the sitemap-index XML.
+ *
+ * Next.js's `generateSitemaps()` API ships chunks at `/sitemap/<id>.xml`
+ * but does NOT emit a single sitemap-index document. Without one,
+ * robots.txt + crawlers point at a 404 and never discover the chunks.
+ * This factory closes that gap: it returns a `GET` Route Handler that
+ * mints a `<sitemapindex>` XML listing every chunk the matching
+ * `createDjangoSitemap` would produce.
+ *
+ * Mount it at **`app/sitemap_index.xml/route.ts`** — NOT `sitemap.xml`.
+ * `app/sitemap.ts` (where `createDjangoSitemap` lives) already owns
+ * `/sitemap.xml` in Next.js's metadata routing, even when its output is
+ * fan-out via `generateSitemaps()` and the singular URL serves 404.
+ * Putting a route handler at `app/sitemap.xml/route.ts` throws at build
+ * time: *Conflicting route and metadata at /sitemap.xml*.
+ *
+ * Usage — the full pattern with the matching chunk + robots factories:
+ *
+ * ```ts
+ * // apps/<app>/app/sitemap.ts — chunks
+ * import { createDjangoSitemap } from '@djangocfg/nextjs/sitemap';
+ * const { generateSitemaps, sitemap } = createDjangoSitemap({ ... });
+ * export { generateSitemaps, sitemap as default };
+ *
+ * // apps/<app>/app/sitemap_index.xml/route.ts — the index
+ * import { createSitemapIndex } from '@djangocfg/nextjs/sitemap';
+ * export const { GET } = createSitemapIndex({
+ *   host: process.env.NEXT_PUBLIC_SITE_URL!,
+ *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+ * });
+ * export const revalidate = 600;
+ *
+ * // apps/<app>/app/robots.ts — point crawlers at the index URL above
+ * import { createRobots } from '@djangocfg/nextjs/sitemap';
+ * const host = process.env.NEXT_PUBLIC_SITE_URL!;
+ * export default createRobots({
+ *   host,
+ *   sitemap: `${host}/sitemap_index.xml`,
+ * });
+ * ```
+ *
+ * Keep `host` / `apiUrl` in sync with the same app's `app/sitemap.ts`
+ * — the index just enumerates the chunks the other file emits.
+ */
+
+import {
+  DEFAULT_INDEX_REVALIDATE,
+  STATIC_ID,
+} from './constants';
+import { fetchSitemapIndex } from './fetch';
+import { encodeChunkId } from './ids';
+
+import type { CreateSitemapIndexOptions } from './types';
+
+interface SitemapIndexRoute {
+  GET: () => Promise<Response>;
+}
+
+export function createSitemapIndex(opts: CreateSitemapIndexOptions): SitemapIndexRoute {
+  const {
+    host,
+    apiUrl,
+    indexRevalidate = DEFAULT_INDEX_REVALIDATE,
+    includeStatic = true,
+  } = opts;
+
+  return {
+    async GET() {
+      const ids: string[] = includeStatic ? [STATIC_ID] : [];
+
+      if (apiUrl) {
+        const index = await fetchSitemapIndex(apiUrl, indexRevalidate);
+        for (const s of index.sources) {
+          for (const c of s.chunks) {
+            ids.push(encodeChunkId(s.name, c.cursor_to));
+          }
+        }
+      }
+
+      const lastmod = new Date().toISOString();
+      const body = renderIndex(host, ids, lastmod);
+
+      return new Response(body, {
+        status: 200,
+        headers: {
+          'content-type': 'application/xml; charset=utf-8',
+          // Mirror the per-chunk revalidate so a cached CDN edge expires
+          // at the same cadence as the index it points at.
+          'cache-control': `public, s-maxage=${indexRevalidate}, stale-while-revalidate=${indexRevalidate}`,
+        },
+      });
+    },
+  };
+}
+
+function renderIndex(host: string, ids: string[], lastmod: string): string {
+  const lines: string[] = [];
+  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+  lines.push('<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">');
+  for (const id of ids) {
+    lines.push('  <sitemap>');
+    lines.push(`    <loc>${escapeXml(`${host}/sitemap/${id}.xml`)}</loc>`);
+    lines.push(`    <lastmod>${lastmod}</lastmod>`);
+    lines.push('  </sitemap>');
+  }
+  lines.push('</sitemapindex>');
+  return lines.join('\n');
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/src/sitemap/index.ts

@@ -10,6 +10,7 @@
  */
 
 export { createDjangoSitemap } from './sitemap';
+export { createSitemapIndex } from './index-route';
 export { createRobots } from './robots';
 export { encodeChunkId, decodeChunkId } from './ids';
 export { fetchSitemapIndex, fetchSitemapFeed } from './fetch';
@@ -21,6 +22,7 @@ export type {
   SitemapIndex,
   SitemapSourceInfo,
   CreateDjangoSitemapOptions,
+  CreateSitemapIndexOptions,
   CreateRobotsOptions,
   StaticRoute,
 } from './types';

package/src/sitemap/robots.ts

@@ -5,15 +5,27 @@
  * defaults cover the common cases (auth, account, API surface) — override
  * per app if needed.
  *
+ * The `sitemap` default `${host}/sitemap.xml` only makes sense for the
+ * single-file case. When the app uses `createDjangoSitemap`
+ * (`generateSitemaps()` → chunked output) **plus** `createSitemapIndex`
+ * — the canonical pairing — pass an explicit
+ * `sitemap: \`${host}/sitemap_index.xml\`` to point crawlers at the
+ * index. The default `/sitemap.xml` will serve a 404 in that setup
+ * (Next.js reserves it for the metadata route but doesn't emit content
+ * there).
+ *
  * Usage:
  *
  * ```ts
  * // apps/<app>/app/robots.ts
  * import { createRobots } from '@djangocfg/nextjs/sitemap';
  *
+ * const host = process.env.NEXT_PUBLIC_SITE_URL!;
+ *
  * export default createRobots({
- *   host: process.env.NEXT_PUBLIC_SITE_URL!,
+ *   host,
  *   disallow: ['/account/', '/auth', '/api/', '/apix/'],
+ *   sitemap: `${host}/sitemap_index.xml`, // matches createSitemapIndex
  * });
  * ```
  */

package/src/sitemap/sitemap.ts

@@ -30,15 +30,16 @@
 
 import type { MetadataRoute } from 'next';
 
+import {
+  DEFAULT_FEED_REVALIDATE,
+  DEFAULT_INDEX_REVALIDATE,
+  STATIC_ID,
+} from './constants';
 import { fetchSitemapFeed, fetchSitemapIndex } from './fetch';
 import { decodeChunkId, encodeChunkId } from './ids';
 
 import type { CreateDjangoSitemapOptions, StaticRoute } from './types';
 
-const STATIC_ID = 'static';
-const DEFAULT_INDEX_REVALIDATE = 600;
-const DEFAULT_FEED_REVALIDATE = 3600;
-
 interface SitemapApi {
   generateSitemaps: () => Promise<Array<{ id: string }>>;
   sitemap: (props: { id: Promise<string> }) => Promise<MetadataRoute.Sitemap>;

package/src/sitemap/types.ts

@@ -70,10 +70,30 @@ export interface CreateDjangoSitemapOptions {
   feedRevalidate?: number;
 }
 
+export interface CreateSitemapIndexOptions {
+  /** Canonical site host, e.g. `https://vamcar.com`. Chunk URLs in the
+   *  index are emitted as `${host}/sitemap/<id>.xml`. */
+  host: string;
+
+  /** Django backend base URL. When omitted, the index lists only the
+   *  static chunk (mirrors `createDjangoSitemap` without `apiUrl`). */
+  apiUrl?: string;
+
+  /** Revalidate window in seconds for both the upstream `index/` fetch
+   *  and the emitted XML's `s-maxage`. Default: 600. */
+  indexRevalidate?: number;
+
+  /** Include the `static` chunk id at the top of the index. Turn off if
+   *  the app's `sitemap.ts` opts out of `staticRoutes`. Default: true. */
+  includeStatic?: boolean;
+}
+
 export interface CreateRobotsOptions {
   host: string;
   /** Disallow patterns. Default: ['/account/', '/auth', '/api/']. */
   disallow?: string[];
-  /** Override sitemap URL. Default: `${host}/sitemap.xml`. */
+  /** Override sitemap URL. Default: `${host}/sitemap.xml`.
+   *  When using `createDjangoSitemap` + `createSitemapIndex`, pass
+   *  `${host}/sitemap_index.xml` — see `createSitemapIndex` JSDoc. */
   sitemap?: string;
 }