1.2.0: local SEO structured data (LocalBusiness, Service, FAQPage), noindex per page, exclude 404 from sitemap, robots param docs

src/modules/seo/buildSitemapEntries.ts

@@ -1,11 +1,10 @@
 import type { BasePayload } from 'payload'
-
-import type { ContentOption } from '../content/index.js'
 import type { I18nConfig } from '../i18n/index.js'
-
-import { archiveFieldName } from '../content/index.js'
-import { buildLocalizedPath, getLocalizedSlugs  } from '../i18n/index.js'
+import { getLocalizedSlugs } from '../i18n/index.js'
+import { buildLocalizedPath } from '../i18n/index.js'
 import { buildHreflangAlternates } from './hreflang.js'
+import type { ContentOption } from '../content/index.js'
+import { archiveFieldName } from '../content/index.js'
 
 /**
  * One sitemap entry, shaped for Next's `app/sitemap.ts`.
@@ -16,50 +15,70 @@ import { buildHreflangAlternates } from './hreflang.js'
  * is the common, weaker kind.
  */
 export type SitemapEntry = {
-  alternates?: { languages: Record<string, string> }
-  changeFrequency?: 'always' | 'daily' | 'hourly' | 'monthly' | 'never' | 'weekly' | 'yearly'
-  lastModified?: Date | string
-  priority?: number
   url: string
+  lastModified?: string | Date
+  changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+  priority?: number
+  alternates?: { languages: Record<string, string> }
 }
 
 type CollectionEntry = {
+  slug: string
   /** Localized segment for entries (archive page slugs), when applicable. */
   prefixSlugs?: Record<string, string>
-  slug: string
 }
 
 type BuildSitemapArgs = {
+  payload: BasePayload
+  config: I18nConfig
   /** Absolute origin, e.g. 'https://example.com'. Required for valid sitemap URLs. */
   baseUrl: string
-  changeFrequency?: SitemapEntry['changeFrequency']
-  config: I18nConfig
+  /** Pages collection slug. Defaults to 'pages'. */
+  pagesSlug?: string
   /** Archive-backed collections, same value as the plugin option. */
   content?: ContentOption
+  /** SiteSettings global slug. Defaults to 'site-settings'. */
+  settingsSlug?: string
   /**
    * Slug of the page that is the site root (collapses to /{locale}).
    * Read from System Pages when omitted.
    */
   homeSlug?: string
-  /** Pages collection slug. Defaults to 'pages'. */
-  pagesSlug?: string
-  payload: BasePayload
-  /** SiteSettings global slug. Defaults to 'site-settings'. */
-  settingsSlug?: string
+  changeFrequency?: SitemapEntry['changeFrequency']
 }
 
 type DocRow = {
-  _status?: string
-  id: number | string
-  meta?: { noindex?: boolean } | null
+  id: string | number
   slug?: unknown
   updatedAt?: string
+  _status?: string
+  meta?: { noindex?: boolean } | null
 }
 
-/** Skip drafts and anything flagged noindex in the SEO tab. */
+/**
+ * Slugs that must never appear in the sitemap — error/system pages that exist as
+ * documents (e.g. a '404' page in the Pages collection) but should not be
+ * indexed. A sitemap should list only real, HTTP-200 content; a '/pl/404' entry
+ * is an audit finding. Matched against the slug in any locale.
+ */
+const EXCLUDED_SITEMAP_SLUGS = new Set(['404', '500', 'not-found', 'error'])
+
+/** True if the doc's slug (in any locale) is an excluded system/error slug. */
+function hasExcludedSlug(slug: unknown): boolean {
+  if (typeof slug === 'string') return EXCLUDED_SITEMAP_SLUGS.has(slug)
+  if (slug && typeof slug === 'object') {
+    for (const value of Object.values(slug as Record<string, unknown>)) {
+      if (typeof value === 'string' && EXCLUDED_SITEMAP_SLUGS.has(value)) return true
+    }
+  }
+  return false
+}
+
+/** Skip drafts, noindex, and system/error pages (404 etc.). */
 function isIndexable(doc: DocRow): boolean {
-  if (doc._status && doc._status !== 'published') {return false}
-  if (doc.meta?.noindex) {return false}
+  if (doc._status && doc._status !== 'published') return false
+  if (doc.meta?.noindex) return false
+  if (hasExcludedSlug(doc.slug)) return false
   return true
 }
 
@@ -77,17 +96,17 @@ function entryFor(
   homeSlug: string | undefined,
   prefix: Record<string, string> | undefined,
   changeFrequency: SitemapEntry['changeFrequency'],
-): null | SitemapEntry {
+): SitemapEntry | null {
   const slugs =
     doc.slug && typeof doc.slug === 'object'
-      ? getLocalizedSlugs({ config, slugField: doc.slug as Record<string, unknown> })
+      ? getLocalizedSlugs({ slugField: doc.slug as Record<string, unknown>, config })
       : {}
 
-  const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })
-  if (!path) {return null}
+  const path = buildLocalizedPath({ slugs, locale, config, homeSlug, prefix })
+  if (!path) return null
 
   const origin = baseUrl.replace(/\/$/, '')
-  const languages = buildHreflangAlternates({ baseUrl, config, homeSlug, prefix, slugs })
+  const languages = buildHreflangAlternates({ slugs, config, baseUrl, homeSlug, prefix })
 
   return {
     url: `${origin}${path}`,
@@ -119,14 +138,14 @@ function entryFor(
  * ```
  */
 export async function buildSitemapEntries({
-  baseUrl,
-  changeFrequency = 'weekly',
-  config,
-  content,
-  homeSlug,
-  pagesSlug = 'pages',
   payload,
+  config,
+  baseUrl,
+  pagesSlug = 'pages',
+  content,
   settingsSlug = 'site-settings',
+  homeSlug,
+  changeFrequency = 'weekly',
 }: BuildSitemapArgs): Promise<SitemapEntry[]> {
   const locales = config.locales.map((l) => l.code)
   const defaultLocale = config.defaultLocale
@@ -135,8 +154,8 @@ export async function buildSitemapEntries({
   // locales so archive prefixes are available per language).
   const settings = (await payload.findGlobal({
     slug: settingsSlug as never,
-    depth: 1,
     locale: 'all' as never,
+    depth: 1,
   })) as Record<string, unknown>
 
   const resolvedHomeSlug =
@@ -159,14 +178,14 @@ export async function buildSitemapEntries({
     // alternates without re-querying per locale.
     const result = await payload.find({
       collection: collection.slug as never,
+      locale: 'all' as never,
       depth: 0,
       limit: 0, // no pagination — sitemap wants everything
-      locale: 'all' as never,
       pagination: false as never,
     })
 
     for (const raw of result.docs as DocRow[]) {
-      if (!isIndexable(raw)) {continue}
+      if (!isIndexable(raw)) continue
 
       // Emit the entry under the default locale's URL; alternates cover the rest.
       const entry = entryFor(
@@ -178,7 +197,7 @@ export async function buildSitemapEntries({
         collection.prefixSlugs,
         changeFrequency,
       )
-      if (entry) {entries.push(entry)}
+      if (entry) entries.push(entry)
     }
   }
 
@@ -187,9 +206,9 @@ export async function buildSitemapEntries({
 
 /** Pulls a slug string from a populated relationship in a specific locale. */
 function extractSlugInLocale(rel: unknown, locale: string): string | undefined {
-  if (!rel || typeof rel !== 'object') {return undefined}
+  if (!rel || typeof rel !== 'object') return undefined
   const slug = (rel as { slug?: unknown }).slug
-  if (typeof slug === 'string') {return slug}
+  if (typeof slug === 'string') return slug
   if (slug && typeof slug === 'object') {
     const v = (slug as Record<string, unknown>)[locale]
     return typeof v === 'string' ? v : undefined
@@ -199,14 +218,14 @@ function extractSlugInLocale(rel: unknown, locale: string): string | undefined {
 
 /** Builds a locale→slug map from a populated archive relationship. */
 function slugMapAllLocales(rel: unknown, locales: string[]): Record<string, string> | undefined {
-  if (!rel || typeof rel !== 'object') {return undefined}
+  if (!rel || typeof rel !== 'object') return undefined
   const slug = (rel as { slug?: unknown }).slug
-  if (!slug || typeof slug !== 'object') {return undefined}
+  if (!slug || typeof slug !== 'object') return undefined
 
   const map: Record<string, string> = {}
   for (const locale of locales) {
     const v = (slug as Record<string, unknown>)[locale]
-    if (typeof v === 'string') {map[locale] = v}
+    if (typeof v === 'string') map[locale] = v
   }
   return Object.keys(map).length ? map : undefined
 }