super-sitemap

Super Sitemap identifies locale routes by looking for a route parameter named locale. The behavior of generated URLs depends on whether the locale route is optional or required in your framework:

Optional Locale Routes

Optional routes omit the default locale from the generated URLs.

• SvelteKit: Use [[locale]] syntax.
• TanStack Start: Use {-$locale} syntax.
• Example Output: /about (default) and /de/about (alternate).

Required Locale Routes

Required routes include the locale segment for every locale, including the default.

• SvelteKit: Use [locale] syntax.
• TanStack Start: Use $locale syntax.
• Example Output: /en/about and /de/about.
• Note: If using required routes, you must manually redirect / to a locale-specific root (like /en) because the root / is not generated.

| Framework      | Optional locale route | Required locale route |
| -------------- | --------------------- | --------------------- |
| SvelteKit      | `[[locale]]`          | `[locale]`            |
| TanStack Start | `{-$locale}`          | `$locale`             |

When your routes contain parameters (e.g., /blog/$slug or /blog/[slug]), you must provide the actual values via the paramValues option to prevent errors and ensure all pages are indexed.

paramValues supports three formats:

1. 1D Array of strings: For simple single-parameter routes.
2. 2D Array of strings: For nested parameters (e.g., ['usa', 'new-york']).
3. Array of ParamValue objects: For fine-grained control over individual entries.

Each ParamValue object can include:

• values (Required): An array of strings representing the parameter values.
• lastmod (Optional): ISO string for the last modification date.
• changefreq (Optional): Frequency of change.
• priority (Optional): Relative importance of the URL.

paramValues: {
  // 1D array
  '/blog/$slug': ['hello-world', 'another-post'],

  // 2D array
  '/campsites/$country/$state': [
    ['usa', 'new-york'],
    ['usa', 'california'],
  ],

  // Array of ParamValue objects
  '/athlete-rankings/$country/$state': [
    {
      values: ['usa', 'new-york'],
      lastmod: '2025-01-01T00:00:00Z',
      changefreq: 'daily',
      priority: 0.5,
    },
  ],
}

Super Sitemap uses a layered architecture consisting of framework-specific Adapters and a framework-agnostic Core.

The Layers

1. Adapters (sveltekit | tanstack-start)

   • Responsibility: Discovering routes using the framework's native mechanisms and parsing framework-specific syntax into a normalized format (NormalizedRoute[]).
   • Note: Adapters do not perform XML rendering or pagination; they only handle route discovery and normalization.

2. Core (src/core/internal/)

   • Responsibility: Path generation, i18n expansion, deduplication, sorting, pagination, XML rendering, and Response building.
   • Constraint: The core has zero framework imports and zero Node.js built-ins, making it highly portable.

The Boundary

All communication between the Adapter and the Core happens via standardized data structures: NormalizedRoute[] or PathObj[]. This ensures the core remains decoupled from framework-specific routing logic.

If your website has more than 50,000 URLs, you should enable Sitemap Index support to comply with sitemaps.org recommendations.

To enable this, you must:

1. Configure your routing so that the sitemap route can serve both the main /sitemap.xml and paginated files like /sitemap1.xml, /sitemap2.xml, etc.
2. Pass the page parameter from your route params into the response function in your sitemap configuration.

Once configured, the sitemap.xml route will automatically return a <sitemapindex> if the total URL count exceeds maxPerPage (defaulting to 50,000), or a standard sitemap if it does not. You can also choose to always treat your sitemap as an index for optimal performance regardless of URL count.

// Example logic for TanStack Start
// /src/routes/sitemap{-$page}[.]xml.ts
import { createFileRoute } from '@tanstack/react-router';
import { response } from 'super-sitemap/tanstack-start';

export const Route = createFileRoute('/sitemap{-$page}.xml')({
  server: {
    handlers: {
      GET: ({ params }) =>
        response({
          origin: 'https://example.com',
          router: getRouter,
          page: params.page,
        }),
    },
  },
});

If you are upgrading from version 1 to version 2, you must apply the following breaking changes:

1. Framework-specific imports: Use the new entry points for your framework:
   • SvelteKit: import * as sitemap from 'super-sitemap/sveltekit'
   • TanStack Start: import * as sitemap from 'super-sitemap/tanstack-start'
2. Locale Configuration: The lang option has been renamed to locales. Use the following shape: locales: { default: 'en', alternates: ['de'] }
3. Dynamic Locale Params: Route parameters used for locales must be named locale:
   • SvelteKit: Use [[locale]] (instead of [[lang]]).
   • TanStack Start: Use {-$locale}.
4. Regex Patterns: excludeRoutePatterns now requires JavaScript RegExp literals instead of strings (e.g., /^\/dashboard/ instead of "^/dashboard").
5. Pattern Matching: excludeRoutePatterns matches against valid paramValues keys; route groups like (authenticated) cannot be matched.
6. Utility Changes: sampledUrls() and sampledPaths() have been removed. Use getSamplePaths() instead.