or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-astrojs--sitemap

Generate a sitemap for your Astro site

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@astrojs/sitemap@3.0.x

To install, run

npx @tessl/cli install tessl/npm-astrojs--sitemap@3.0.0

index.mddocs/

@astrojs/sitemap

@astrojs/sitemap is an Astro integration that automatically generates XML sitemaps for Astro websites during the build process. It provides comprehensive sitemap generation capabilities including support for static and dynamic routes, internationalization (i18n) with alternate language links, customizable filtering and serialization of pages, configurable entry limits for large sites with automatic sitemap splitting, and advanced configuration options for changefreq, lastmod, and priority metadata.

Package Information

  • Package Name: @astrojs/sitemap
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @astrojs/sitemap

Core Imports

import sitemap from "@astrojs/sitemap";

For type imports when configuring:

import sitemap, { type SitemapOptions, type ChangeFreq, type SitemapItem, type LinkItem, ChangeFreqEnum } from "@astrojs/sitemap";

Basic Usage

// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [sitemap()],
});

Basic configuration with options:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      filter: (page) => !page.includes('/admin/'),
      changefreq: 'weekly',
      priority: 0.7,
      lastmod: new Date(),
      entryLimit: 10000
    })
  ],
});

Architecture

The integration operates within Astro's build lifecycle:

  • Build Hook Integration: Hooks into astro:build:done to generate sitemaps after the build completes
  • Route Discovery: Automatically discovers static and dynamic routes from Astro's pages and routes
  • URL Processing: Processes URLs with support for trailing slash configuration and base paths
  • Internationalization: Supports i18n with alternate language links in sitemaps
  • Sitemap Splitting: Automatically splits large sitemaps into multiple files with a sitemap index
  • Customization Layer: Provides filtering, serialization, and custom page inclusion capabilities

Capabilities

Integration Function

Main factory function that creates the Astro sitemap integration.

/**
 * Creates an Astro integration for sitemap generation
 * @param options - Optional configuration for sitemap generation
 * @returns AstroIntegration instance
 */
function sitemap(options?: SitemapOptions): AstroIntegration;

Page Filtering

Filter pages to include or exclude from the sitemap.

interface SitemapOptions {
  /**
   * Function to filter pages by URL
   * @param page - Full URL of the page
   * @returns true to include page, false to exclude
   */
  filter?(page: string): boolean;
}

Custom Pages

Include additional pages not generated by Astro.

interface SitemapOptions {
  /** Array of custom page URLs to include in sitemap */
  customPages?: string[];
}

Canonical URL Override

Override the site URL for sitemap generation (alternative to astro.config site option).

interface SitemapOptions {
  /** Canonical URL to use instead of astro.config.site */
  canonicalURL?: string;
}

Internationalization

Configure i18n support with alternate language links.

interface SitemapOptions {
  i18n?: {
    /** Default locale key that must exist in locales */
    defaultLocale: string;
    /** Map of locale keys to language codes (e.g., 'en' -> 'en-US') */
    locales: Record<string, string>;
  };
}

Entry Limit Configuration

Control sitemap file splitting for large sites.

interface SitemapOptions {
  /** Maximum number of entries per sitemap file (default: 45000) */
  entryLimit?: number;
}

Sitemap Metadata

Configure global sitemap metadata.

interface SitemapOptions {
  /** Change frequency for all pages */
  changefreq?: ChangeFreq;
  /** Last modification date for all pages */
  lastmod?: Date;
  /** Priority value for all pages (0-1) */
  priority?: number;
}

Custom Serialization

Customize individual sitemap entries before writing.

interface SitemapOptions {
  /**
   * Function called for each sitemap entry before writing to disk
   * @param item - Sitemap item to customize
   * @returns Modified item, undefined to exclude, or Promise for async processing
   */
  serialize?(item: SitemapItem): SitemapItem | Promise<SitemapItem | undefined> | undefined;
}

Types

SitemapOptions

Complete configuration interface for the sitemap integration.

type SitemapOptions = {
  filter?(page: string): boolean;
  customPages?: string[];
  canonicalURL?: string;
  i18n?: {
    defaultLocale: string;
    locales: Record<string, string>;
  };
  entryLimit?: number;
  changefreq?: ChangeFreq;
  lastmod?: Date;
  priority?: number;
  serialize?(item: SitemapItem): SitemapItem | Promise<SitemapItem | undefined> | undefined;
} | undefined;

SitemapItem

Represents a single entry in the sitemap.

interface SitemapItem {
  /** Absolute URL of the page */
  url: string;
  /** Last modification date (ISO string) */
  lastmod?: string;
  /** Change frequency */
  changefreq?: ChangeFreq;
  /** Priority value (0-1) */
  priority?: number;
  /** Alternate language links for i18n */
  links?: LinkItem[];
}

LinkItem

Represents alternate language links for internationalization.

interface LinkItem {
  /** Fully-qualified URL for this language version */
  url: string;
  /** Language code (e.g., 'en-US', 'es-ES') */
  lang: string;
}

ChangeFreq

String union type for sitemap changefreq values.

type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';

ChangeFreqEnum

Enum export for changefreq values (re-exported from 'sitemap' package).

enum ChangeFreqEnum {
  ALWAYS = 'always',
  HOURLY = 'hourly',
  DAILY = 'daily',
  WEEKLY = 'weekly',
  MONTHLY = 'monthly',
  YEARLY = 'yearly',
  NEVER = 'never'
}

Usage Examples

Advanced Filtering

// astro.config.mjs
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      filter: (page) => {
        // Exclude admin pages and draft content
        return !page.includes('/admin/') && 
               !page.includes('/draft/') &&
               !page.includes('?preview=');
      }
    })
  ],
});

Internationalization Setup

// astro.config.mjs
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      i18n: {
        defaultLocale: 'en',
        locales: {
          en: 'en-US',
          es: 'es-ES',
          fr: 'fr-FR'
        }
      }
    })
  ],
});

Custom Serialization

// astro.config.mjs
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      serialize(item) {
        // Set different priorities based on page type
        if (item.url.includes('/blog/')) {
          item.priority = 0.8;
          item.changefreq = 'weekly';
        } else if (item.url.includes('/products/')) {
          item.priority = 0.9;
          item.changefreq = 'daily';
        } else if (item.url.includes('/archive/')) {
          // Exclude archive pages
          return undefined;
        }
        
        // Set last modified date
        item.lastmod = new Date().toISOString();
        
        return item;
      }
    })
  ],
});

Large Site Configuration

// astro.config.mjs
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      entryLimit: 10000, // Split into multiple files
      customPages: [
        'https://example.com/external-app',
        'https://example.com/api-docs'
      ]
    })
  ],
});

Alternative Canonical URL

// astro.config.mjs
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  // No site option required when using canonicalURL
  integrations: [
    sitemap({
      canonicalURL: 'https://example.com',
      customPages: [
        'https://example.com/spa-pages'
      ]
    })
  ],
});