@power-seo/sitemap

XML sitemap generation for TypeScript — streaming output, automatic index splitting, image/video/news extensions, and URL validation — works in Next.js, Remix, Express, and edge runtimes with zero runtime dependencies.

@power-seo/sitemap produces standards-compliant <urlset> and <sitemapindex> XML from typed URL arrays. Provide a hostname and URL list — get back a valid XML string ready to serve as Content-Type: application/xml. For large catalogs, stream chunks with constant memory usage or auto-split at the 50,000-URL spec limit with a generated index file. All six functions are independently importable and tree-shakeable.

Zero runtime dependencies — only @power-seo/core as a peer.

Why @power-seo/sitemap?

| | Without | With | | ----------------- | ----------------------------------------- | --------------------------------------------------- | | Spec compliance | ❌ Hand-built XML, wrong namespaces | ✅ Correct <urlset> + namespace declarations | | Large sites | ❌ Single file breaks at 50,000 URLs | ✅ Auto-split + sitemap index generation | | Memory usage | ❌ String concat spikes on large catalogs | ✅ Synchronous generator yields chunks | | Image indexing | ❌ Product images undiscoverable | ✅ <image:image> extension per URL | | Video SEO | ❌ No structured video metadata | ✅ <video:video> extension with title, duration | | News sitemaps | ❌ Missing publication + date tags | ✅ <news:news> extension for Google News | | Hostname handling | ❌ Hardcode absolute URLs everywhere | ✅ Pass hostname once; use relative loc paths | | Validation | ❌ Silent bad data reaches Google | ✅ validateSitemapUrl() returns errors + warnings |

Features

• Full sitemap spec support — <loc>, <lastmod>, <changefreq>, <priority>, all optional elements
• Hostname + relative paths — pass hostname in config; loc can be a relative path like /about
• Image sitemap extension — <image:image> tags with loc, caption, title, geoLocation, license
• Video sitemap extension — <video:video> tags with title, description, thumbnail, duration, rating
• News sitemap extension — <news:news> tags with publication name, language, date
• Streaming generation — streamSitemap() is a synchronous generator yielding XML string chunks; no memory spike on large lists
• Automatic index splitting — splitSitemap() chunks at MAX_URLS_PER_SITEMAP (50,000) and returns both sitemaps and the index XML
• Sitemap index generation — generateSitemapIndex() creates a <sitemapindex> pointing to child sitemaps
• Smart namespace detection — generateSitemap() only declares XML namespaces for extensions (image, video, news) that are actually used
• URL validation — validateSitemapUrl() returns { valid, errors, warnings } without throwing
• Next.js App Router adapter — toNextSitemap() converts SitemapURL[] to the MetadataRoute.Sitemap[] format for app/sitemap.ts
• Constants exported — MAX_URLS_PER_SITEMAP (50,000) and MAX_SITEMAP_SIZE_BYTES (52,428,800)
• Framework-agnostic — works in Next.js API routes, Remix loaders, Express, Fastify, and edge runtimes
• Full TypeScript support — typed SitemapURL, SitemapImage, SitemapVideo, SitemapNews, SitemapConfig
• Zero runtime dependencies — pure TypeScript, no external XML libraries
• Tree-shakeable — import only the functions you use

Comparison

| Feature | @power-seo/sitemap | next-sitemap | sitemap (npm) | xmlbuilder2 | | -------------------------------- | :----------------: | :----------: | :-----------: | :---------: | | Image sitemap extension | ✅ | ✅ | ✅ | ❌ | | Video sitemap extension | ✅ | ❌ | ✅ | ❌ | | News sitemap extension | ✅ | ❌ | ✅ | ❌ | | Streaming generation | ✅ | ❌ | ❌ | ❌ | | Auto index splitting | ✅ | ✅ | ❌ | ❌ | | URL validation | ✅ | ❌ | ❌ | ❌ | | Hostname + relative loc paths | ✅ | ❌ | ❌ | ❌ | | Zero runtime dependencies | ✅ | ❌ | ❌ | ❌ | | Edge runtime compatible | ✅ | ❌ | ❌ | ❌ | | TypeScript-first | ✅ | Partial | ❌ | ❌ | | Tree-shakeable | ✅ | ❌ | ❌ | ❌ | | Next.js app/sitemap.ts adapter | ✅ | ✅ | ❌ | ❌ |

Installation

npm install @power-seo/sitemap

yarn add @power-seo/sitemap

pnpm add @power-seo/sitemap

Quick Start

import { generateSitemap } from '@power-seo/sitemap';

const xml = generateSitemap({
  hostname: 'https://example.com',
  urls: [
    { loc: '/', lastmod: '2026-01-01', changefreq: 'daily', priority: 1.0 },
    { loc: '/about', changefreq: 'monthly', priority: 0.8 },
    { loc: '/blog/post-1', lastmod: '2026-01-15', priority: 0.6 },
  ],
});

// Returns valid XML string:
// <?xml version="1.0" encoding="UTF-8"?>
// <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
//   <url><loc>https://example.com/</loc>...

hostname is required — it is prepended to any loc value that is a relative path. Absolute loc values (starting with http) are used as-is.

Usage

Generating a Sitemap

generateSitemap() accepts a SitemapConfig with hostname and urls and returns a complete XML string.

import { generateSitemap } from '@power-seo/sitemap';

const xml = generateSitemap({
  hostname: 'https://example.com',
  urls: [
    { loc: '/', lastmod: '2026-01-01', changefreq: 'daily', priority: 1.0 },
    { loc: '/products', changefreq: 'weekly', priority: 0.9 },
    { loc: '/blog', changefreq: 'daily', priority: 0.8 },
  ],
});

// Serve as application/xml
res.setHeader('Content-Type', 'application/xml');
res.send(xml);

Streaming a Large Sitemap

streamSitemap() is a synchronous generator. It yields XML string chunks one <url> at a time — keeping memory usage constant regardless of catalog size.

import { streamSitemap } from '@power-seo/sitemap';

const urls = fetchAllProductUrls(); // Iterable<SitemapURL>

const stream = streamSitemap('https://example.com', urls);
for (const chunk of stream) {
  response.write(chunk);
}
response.end();

Splitting Large Sitemaps with an Index

splitSitemap() chunks a config at the 50,000-URL spec limit and returns all individual sitemap XML strings plus a sitemap index XML string that references them.

import { splitSitemap } from '@power-seo/sitemap';

const { index, sitemaps } = splitSitemap({
  hostname: 'https://example.com',
  urls: largeUrlArray, // more than 50,000 entries
});

// Write each sitemap file
for (const { filename, xml } of sitemaps) {
  fs.writeFileSync(`./public${filename}`, xml);
}

// Write the index (default filenames: /sitemap-0.xml, /sitemap-1.xml, ...)
fs.writeFileSync('./public/sitemap.xml', index);

Custom filename pattern:

const { index, sitemaps } = splitSitemap(
  { hostname: 'https://example.com', urls: largeUrlArray },
  '/sitemaps/part-{index}.xml', // default: '/sitemap-{index}.xml'
);

Generating a Sitemap Index Manually

Use generateSitemapIndex() when you maintain separate sitemaps per section or locale and want to combine them under a single index file.

import { generateSitemapIndex } from '@power-seo/sitemap';

const indexXml = generateSitemapIndex({
  sitemaps: [
    { loc: 'https://example.com/sitemap-pages.xml', lastmod: '2026-01-01' },
    { loc: 'https://example.com/sitemap-products.xml', lastmod: '2026-01-15' },
    { loc: 'https://example.com/sitemap-blog.xml', lastmod: '2026-01-20' },
  ],
});

Image Sitemaps

Add images to any SitemapURL entry to emit <image:image> extension tags:

import { generateSitemap } from '@power-seo/sitemap';

const xml = generateSitemap({
  hostname: 'https://example.com',
  urls: [
    {
      loc: '/products/blue-sneaker',
      lastmod: '2026-01-10',
      images: [
        {
          loc: 'https://cdn.example.com/sneaker-blue.jpg',
          caption: 'Blue sneaker — side view',
          title: 'Blue Running Sneaker',
        },
        {
          loc: 'https://cdn.example.com/sneaker-blue-top.jpg',
          caption: 'Blue sneaker — top view',
        },
      ],
    },
  ],
});

Validating URL Entries

validateSitemapUrl() checks a SitemapURL against the sitemap spec and returns structured errors and warnings — useful in CI or before serving.

import { validateSitemapUrl } from '@power-seo/sitemap';

const result = validateSitemapUrl({
  loc: '/about',
  priority: 1.5, // out of range
  changefreq: 'daily',
});

// result.valid   → false
// result.errors  → ['priority must be between 0.0 and 1.0']
// result.warnings → []

Next.js App Router — app/sitemap.ts Convention

Next.js App Router has a built-in app/sitemap.ts file convention that returns an array of URL objects (not XML). Use toNextSitemap() to convert SitemapURL[] to the required format:

// app/sitemap.ts
import { toNextSitemap } from '@power-seo/sitemap';

export default async function sitemap() {
  const urls = await fetchUrlsFromCms();

  return toNextSitemap(urls);
  // Returns NextSitemapEntry[] — Next.js renders the XML automatically
}

toNextSitemap() filters out invalid URLs and maps changefreq to changeFrequency as required by Next.js. The lastmod field is passed through as-is (string or Date).

Next.js App Router — Route Handler (XML)

For full control over the XML output (useful when you need image/video/news extensions), use a route handler instead:

// app/sitemap.xml/route.ts
import { generateSitemap } from '@power-seo/sitemap';

export async function GET() {
  const urls = await fetchUrlsFromCms();

  const xml = generateSitemap({
    hostname: 'https://example.com',
    urls,
  });

  return new Response(xml, {
    headers: { 'Content-Type': 'application/xml' },
  });
}

Remix Resource Route

// app/routes/sitemap[.xml].ts
import { generateSitemap } from '@power-seo/sitemap';
import type { LoaderFunctionArgs } from '@remix-run/node';

export async function loader({ request }: LoaderFunctionArgs) {
  const urls = await fetchUrlsFromDb();

  const xml = generateSitemap({
    hostname: 'https://example.com',
    urls,
  });

  return new Response(xml, {
    headers: { 'Content-Type': 'application/xml' },
  });
}

API Reference

generateSitemap(config)

function generateSitemap(config: SitemapConfig): string;

| Prop | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------- | | hostname | string | ✅ | Base URL prepended to relative loc paths (e.g. 'https://example.com') | | urls | SitemapURL[] | ✅ | Array of URL entries | | maxUrlsPerSitemap | number | — | Override the 50,000-URL chunk size (used by splitSitemap) | | outputDir | string | — | Optional output directory hint (informational; does not write files) |

streamSitemap(hostname, urls)

function streamSitemap(
  hostname: string,
  urls: Iterable<SitemapURL>,
): Generator<string, void, undefined>;

Synchronous generator. Yields XML string chunks — one for the XML declaration and opening tag, one per <url> block, and one for the closing tag. Does not buffer the full XML in memory.

| Param | Type | Description | | ---------- | ---------------------- | ------------------------------------------------------------------ | | hostname | string | Base URL prepended to relative loc paths | | urls | Iterable<SitemapURL> | Any iterable of URL entries — arrays, generators, database cursors |

splitSitemap(config, sitemapUrlPattern?)

function splitSitemap(
  config: SitemapConfig,
  sitemapUrlPattern?: string,
): { index: string; sitemaps: Array<{ filename: string; xml: string }> };

Splits a large URL set into multiple sitemap files and returns the index XML and all sitemap XMLs. The sitemapUrlPattern parameter controls generated filenames using {index} as a placeholder.

| Param | Type | Default | Description | | ------------------- | --------------- | ------------------------ | --------------------------------------- | | config | SitemapConfig | — | Same config as generateSitemap() | | sitemapUrlPattern | string | '/sitemap-{index}.xml' | Filename pattern for each split sitemap |

Return value:

| Field | Type | Description | | ---------- | ------------------------------------------ | ---------------------------------------------------------------- | | index | string | Sitemap index XML (<sitemapindex>) referencing all split files | | sitemaps | Array<{ filename: string; xml: string }> | Each split sitemap with its filename and XML string |

generateSitemapIndex(config)

function generateSitemapIndex(config: SitemapIndexConfig): string;

| Prop | Type | Description | | ---------- | --------------------- | ---------------------------------------------------- | | sitemaps | SitemapIndexEntry[] | Array of { loc: string; lastmod?: string } entries |

validateSitemapUrl(url)

function validateSitemapUrl(url: SitemapURL): SitemapValidationResult;

Returns { valid: boolean; errors: string[]; warnings: string[] }. Never throws.

toNextSitemap(urls)

import { toNextSitemap } from '@power-seo/sitemap';

function toNextSitemap(urls: SitemapURL[]): NextSitemapEntry[];

Converts a SitemapURL[] to the array format expected by Next.js App Router's app/sitemap.ts file convention. Invalid URLs (per validateSitemapUrl) are filtered out automatically. changefreq is mapped to changeFrequency.

| Field | Type | Description | | ----------------- | ---------------- | ------------------------------------- | | url | string | Absolute URL (loc) | | lastModified | Date \| string | From lastmod (passed through as-is) | | changeFrequency | string | From changefreq | | priority | number | From priority |

Types

| Type | Description | | ------------------------- | --------------------------------------------------------------------------------------------- | | SitemapConfig | { hostname: string; urls: SitemapURL[]; maxUrlsPerSitemap?: number; outputDir?: string } | | SitemapURL | Single URL entry — see field table below | | SitemapImage | { loc: string; caption?: string; geoLocation?: string; title?: string; license?: string } | | SitemapVideo | Video extension entry with thumbnailLoc, title, description, and optional fields | | SitemapNews | { publication: { name: string; language: string }; publicationDate: string; title: string } | | SitemapIndexConfig | { sitemaps: SitemapIndexEntry[] } | | SitemapIndexEntry | { loc: string; lastmod?: string } | | SitemapValidationResult | { valid: boolean; errors: string[]; warnings: string[] } |

SitemapURL Fields

| Prop | Type | Default | Description | | ------------ | --------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ | | loc | string | — | Required. URL path (e.g. /about) or absolute URL. Hostname is prepended to relative paths. | | lastmod | string | — | Last modified date — ISO 8601 or YYYY-MM-DD | | changefreq | 'always' \| 'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'yearly' \| 'never' | — | Suggested crawl frequency | | priority | number | (no tag emitted) | Priority 0.0–1.0. When omitted, no <priority> tag is written. | | images | SitemapImage[] | — | Image extension entries — emits <image:image> blocks | | videos | SitemapVideo[] | — | Video extension entries — emits <video:video> blocks | | news | SitemapNews | — | News extension entry — emits <news:news> block |

Constants

| Constant | Value | Description | | ------------------------ | ------------ | ------------------------------------------------------------- | | MAX_URLS_PER_SITEMAP | 50_000 | Maximum URLs allowed per sitemap file (spec limit) | | MAX_SITEMAP_SIZE_BYTES | 52_428_800 | Maximum sitemap file size in bytes (50 MB = 50 × 1024 × 1024) |

Use Cases

• Next.js App Router — generate sitemaps in app/sitemap.xml/route.ts at request time or build time
• E-commerce catalogs — product image sitemaps with <image:image> for every listing; keep Google Images up to date
• News publishers — <news:news> extension for Google News sitemap submission
• Multi-locale sites — separate sitemaps per locale with a unified sitemap index
• Programmatic SEO — generate sitemaps for thousands of auto-generated pages with no memory overhead
• Large sites — automatic splitting at 50,000 URLs per file with a generated index
• Video platforms — <video:video> extension with title, description, and thumbnail for video SEO
• CI/CD pipelines — validate URL entries with validateSitemapUrl() as part of pull request checks

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero runtime dependencies — only @power-seo/core as a peer dependency
• Framework-agnostic — works in any JavaScript environment that supports ES2020+
• SSR compatible — safe to run in Next.js Server Components, Remix loaders, or Express handlers
• Edge runtime safe — no fs, no path, no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno
• Synchronous generator streaming — streamSitemap() uses function* — no async overhead, no backpressure complexity
• Smart namespace detection — generateSitemap() only declares image/video/news namespaces when actually used; streamSitemap() always includes all namespaces for simplicity
• Tree-shakeable — "sideEffects": false with named exports per function
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

| Package | Install | Description | | ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- | | @power-seo/core | npm i @power-seo/core | Framework-agnostic utilities, types, validators, and constants | | @power-seo/react | npm i @power-seo/react | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs | | @power-seo/meta | npm i @power-seo/meta | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR | | @power-seo/schema | npm i @power-seo/schema | Type-safe JSON-LD structured data — 23 builders + 22 React components | | @power-seo/content-analysis | npm i @power-seo/content-analysis | Yoast-style SEO content scoring engine with React components | | @power-seo/readability | npm i @power-seo/readability | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI | | @power-seo/preview | npm i @power-seo/preview | SERP, Open Graph, and Twitter/X Card preview generators | | @power-seo/sitemap | npm i @power-seo/sitemap | XML sitemap generation, streaming, index splitting, and validation | | @power-seo/redirects | npm i @power-seo/redirects | Redirect engine with Next.js, Remix, and Express adapters | | @power-seo/links | npm i @power-seo/links | Link graph analysis — orphan detection, suggestions, equity scoring | | @power-seo/audit | npm i @power-seo/audit | Full SEO audit engine — meta, content, structure, performance rules | | @power-seo/images | npm i @power-seo/images | Image SEO — alt text, lazy loading, format analysis, image sitemaps | | @power-seo/ai | npm i @power-seo/ai | LLM-agnostic AI prompt templates and parsers for SEO tasks | | @power-seo/analytics | npm i @power-seo/analytics | Merge GSC + audit data, trend analysis, ranking insights, dashboard | | @power-seo/search-console | npm i @power-seo/search-console | Google Search Console API — OAuth2, service account, URL inspection | | @power-seo/integrations | npm i @power-seo/integrations | Semrush and Ahrefs API clients with rate limiting and pagination | | @power-seo/tracking | npm i @power-seo/tracking | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License