@djangocfg/nextjs 2.1.416 → 2.1.417

package/dist/sitemap/index.d.mts

@@ -74,7 +74,9 @@ 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;
 }
 
@@ -119,27 +121,45 @@ interface SitemapApi {
 declare function createDjangoSitemap(opts: CreateDjangoSitemapOptions): SitemapApi;
 
 /**
- * createSitemapIndex — Route Handler factory for `app/sitemap.xml/route.ts`.
+ * 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.xml` index. Without one,
+ * 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.
  *
- * Usage:
+ * 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.xml/route.ts
- * import { createSitemapIndex } from '@djangocfg/nextjs/sitemap';
+ * // 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`
@@ -158,15 +178,27 @@ declare function createSitemapIndex(opts: CreateSitemapIndexOptions): SitemapInd
  * 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/dist/sitemap/index.mjs.map

@@ -1 +1 @@
-{"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 `app/sitemap.xml/route.ts`.\n *\n * Next.js's `generateSitemaps()` API ships chunks at `/sitemap/<id>.xml`\n * but does NOT emit a single `/sitemap.xml` index. 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 * Usage:\n *\n * ```ts\n * // apps/<app>/app/sitemap.xml/route.ts\n * import { createSitemapIndex } from '@djangocfg/nextjs/sitemap';\n *\n * export const { GET } = createSitemapIndex({\n *   host: process.env.NEXT_PUBLIC_SITE_URL!,\n *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,\n * });\n *\n * export const revalidate = 600;\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 * 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":"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","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":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.416",
+  "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.416",
-    "@djangocfg/monitor": "^2.1.416",
-    "@djangocfg/ui-core": "^2.1.416",
+    "@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.416",
-    "@djangocfg/monitor": "^2.1.416",
-    "@djangocfg/ui-core": "^2.1.416",
-    "@djangocfg/layouts": "^2.1.416",
-    "@djangocfg/typescript-config": "^2.1.416",
+    "@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/index-route.ts

@@ -1,25 +1,43 @@
 /**
- * createSitemapIndex — Route Handler factory for `app/sitemap.xml/route.ts`.
+ * 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.xml` index. Without one,
+ * 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.
  *
- * Usage:
+ * 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.xml/route.ts
- * import { createSitemapIndex } from '@djangocfg/nextjs/sitemap';
+ * // 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`

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/types.ts

@@ -92,6 +92,8 @@ 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;
 }