โš  Breaking Change โ€” API Authentication Header

The API authentication header has been renamed from X-API-Key to Authorization: Bearer <token>. Update all API calls before upgrading. Legacy X-API-Key support will be removed in v4.0.0.

๐Ÿ”€ Migration Guide from v3.1.x โ†’ v3.2.1

1

Update Authentication Header

Replace all instances of X-API-Key with the new Bearer token format.

- headers: { 'X-API-Key': process.env.API_KEY }
+ headers: { 'Authorization': 'Bearer ' + process.env.API_KEY }
2

Update Dependencies

Run the dependency update command to pull in the new version of all sub-packages.

// package.json
- "@sitemap/xml": "^3.1.8",
- "@sitemap/api": "^3.1.5",
+ "@sitemap/xml": "^3.2.1",
+ "@sitemap/api": "^3.2.1",
3

Regenerate Sitemap Index

After updating, regenerate your sitemap index to apply the new URL encoding standards.

$ npm run sitemap:regenerate -- --force
โœจ

New Features (7)

Real-time Multi-site Synchronization

New

Added WebSocket-based synchronization across multiple sites. When content changes on one site, all linked sitemaps update instantly within the cluster.

// Enable multi-site sync
const sync = new MultiSiteSync({
  sites: ['site-a', 'site-b', 'site-c'],
  syncInterval: 'realtime',  // 'realtime' | 'every-5m' | 'hourly'
  autoResolve: true,
});
sync.start();
๐Ÿ‘ค @jchen ๐Ÿ”– #1247 ๐Ÿ“ฆ @sitemap/sync@1.0.0

AI-Powered URL Priority Scoring

New

Integrates an ML model that analyzes page content, link depth, and historical crawl data to automatically assign optimal priority scores to every URL in your sitemap.

๐Ÿ‘ค @mskaria ๐Ÿ”– #1239 ๐Ÿ“ฆ @sitemap/ai-priority@0.1.0

Edge-Deployed Sitemap Rendering

New

Sitemaps can now be rendered at the edge via Cloudflare Workers, Vercel Edge Functions, or Deno Deploy. Eliminates cold-start latency for large sitemap requests.

๐Ÿ‘ค @nwilson ๐Ÿ”– #1251

Bulk URL Submission to Bing & Yandex

New

New native integrations for bulk URL submission to Bing Webmaster Tools and Yandex Webmaster. Submit up to 10,000 URLs per batch.

// Submit to multiple engines at once
client.submit({
  urls: urlList,
  engines: ['google', 'bing', 'yandex'],
  batchSize: 10000,
});
๐Ÿ‘ค @lzhao ๐Ÿ”– #1244

Sitemap Visualizer Dashboard

New

New interactive dashboard that renders your sitemap as a navigable tree graph. Click any node to see indexing status, crawl date, and performance metrics.

๐Ÿ‘ค @rkim ๐Ÿ”– #1255

Webhook Events for Indexing Lifecycle

New

Configurable webhook endpoints for url.added, url.indexed, url.removed, and sitemap.regenerated events. Includes retry logic with exponential backoff.

๐Ÿ‘ค @jchen ๐Ÿ”– #1230

GraphQL API Query Support

New

The API now supports GraphQL alongside REST. Query sitemaps, URLs, and indexing stats with a single flexible request.

๐Ÿ‘ค @mskaria ๐Ÿ”– #1248
โšก

Improvements (12)

40% Faster XML Generation for Large Sitemaps

Improved

Refactored the XML streaming pipeline using async generators. Sitemaps with 1M+ URLs now generate in under 8 seconds (was ~13s). Memory footprint reduced by 60%.

๐Ÿ‘ค @nwilson ๐Ÿ”– #1258

Improved Hreflang Tag Validation

Improved

Enhanced validation logic for hreflang attributes now catches 15+ previously undetected edge cases, including circular references and invalid region codes.

๐Ÿ‘ค @lzhao ๐Ÿ”– #1241

Retry Logic for Failed Indexing Submissions

Improved

Added exponential backoff with jitter for API calls to search engine indexing endpoints. Failed submissions now retry up to 5 times before marking as errored.

๐Ÿ‘ค @jchen ๐Ÿ”– #1253

Node.js 22 LTS Support

Improved

Full compatibility with Node.js 22 LTS including improved worker thread utilization and native fetch support for API calls.

๐Ÿ‘ค @mskaria ๐Ÿ”– #1260

Compressed Sitemap Index Files

Improved

Sitemap index files are now automatically gzip-compressed when served, reducing bandwidth usage by up to 75% for large index files.

๐Ÿ‘ค @rkim ๐Ÿ”– #1236

Improved TypeScript Definitions

Improved

All public APIs now have complete TypeScript type definitions. Generic support for custom URL objects and configuration types.

๐Ÿ‘ค @nwilson ๐Ÿ”– #1249

Reduced Bundle Size for Browser SDK

Improved

Treeshaking improvements and code splitting reduced the browser SDK bundle from 48KB to 29KB (minified + gzipped).

๐Ÿ‘ค @lzhao ๐Ÿ”– #1245
๐Ÿ›

Bug Fixes (9)

Fixed: Duplicate URLs in Sitemap with Pagination

Fixed

Resolved an issue where paginated URLs (e.g., /page/1 and ?page=1) were incorrectly deduplicated, causing valid alternate URLs to be excluded.

๐Ÿ‘ค @jchen ๐Ÿ”– #1262

Fixed: Incorrect LastMod Dates After Redirect Resolution

Fixed

When resolving 301/302 redirects during crawling, the <lastmod> field now correctly reflects the final destination's modification date, not the redirect chain's first entry.

๐Ÿ‘ค @mskaria ๐Ÿ”– #1259

Fixed: Memory Leak in Long-Running Crawl Sessions

Fixed

Fixed a memory leak in the crawler's URL queue that caused gradual memory growth during sessions lasting more than 4 hours. Memory now stabilizes after initial warmup.

๐Ÿ‘ค @nwilson ๐Ÿ”– #1257

Fixed: Video Sitemap Thumbnail URLs Not Encoded

Fixed

Video thumbnail URLs containing special characters (e.g., ?, &, #) are now properly percent-encoded before XML serialization.

๐Ÿ‘ค @lzhao ๐Ÿ”– #1250

Fixed: Rate Limit Not Respected for Google Indexing API

Fixed

Google's indexing API rate limit (100 requests/day per property) is now correctly tracked and enforced across all concurrent submissions within the same project.

๐Ÿ‘ค @rkim ๐Ÿ”– #1246

Fixed: WordPress Plugin Conflict with Yoast SEO

Fixed

Resolved conflict where both plugins attempted to register the same /sitemap.xml rewrite rule, causing 404 errors on WordPress 6.5+.

๐Ÿ‘ค @jchen ๐Ÿ”– #1243

Fixed: Cron Job Overlap on Multi-Instance Deployments

Fixed

Added distributed locking via Redis for scheduled sitemap regeneration tasks. Prevents duplicate regeneration when multiple server instances are running.

๐Ÿ‘ค @nwilson ๐Ÿ”– #1240
๐Ÿ”’

Security Fixes (2)

CVE-2025-0142: XML Entity Injection in Custom URL Processing

Security

Fixed an XXE (XML External Entity) injection vulnerability in the custom URL processing pipeline. Malicious URLs could have triggered SSRF attacks when passed through the sitemap generator. Users upgrading from any version before 3.2.0 should upgrade immediately.

๐Ÿ‘ค @security-team ๐Ÿ”– CVE-2025-0142 ๐Ÿ“ฆ @sitemap/core@3.2.1

Authentication Bypass in Webhook Configuration API

Security

Fixed a logic flaw in the webhook configuration endpoint (/api/v2/webhooks) that allowed unauthenticated POST requests under specific conditions. All webhook configurations should be re-audited after upgrading.

๐Ÿ‘ค @security-team ๐Ÿ”– CVE-2025-0143
โš 

Deprecated (1)

SitemapGenerator.addUrl() deprecated in favor of addUrlAsync()

Deprecated

The synchronous addUrl() method is deprecated. Use addUrlAsync() for non-blocking URL additions. The synchronous method will be removed in v4.0.0.

๐Ÿ‘ค @nwilson ๐Ÿ”– #1261