@corentints/tanstack-router-sitemap

Generate XML sitemaps automatically from your TanStack Router route definitions. This plugin integrates seamlessly with TanStack Router to create SEO-friendly sitemaps without manual configuration. It supports Tanstack Router and Tanstack Start!

Features

• 🚀 Automatic sitemap generation from TanStack Router routes
• 🔧 Flexible configuration options for different use cases
• 🎯 Smart route filtering - excludes dynamic routes by default
• 📝 Customizable metadata per route (priority, changefreq, lastmod)
• 🌐 SEO optimized XML output following sitemap.org standards
• ⚡ Vite plugin support for seamless integration
• 🔍 TypeScript support with full type definitions
• 📋 Manual route generation for dynamic content (blog posts, articles, etc.)

Installation

npm install @corentints/tanstack-router-sitemap

Quick Start

1. As a Vite Plugin (Recommended)

Tanstack Router

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import { sitemapPlugin } from '@corentints/tanstack-router-sitemap';

export default defineConfig({
  plugins: [
    // ... your other plugins
    sitemapPlugin({
      baseUrl: 'https://your-domain.com',
      outputPath: 'public/sitemap.xml',
    }),
  ],
});

Tanstack Start

Add the plugin to your app.config.ts:

export default defineConfig({
  // ...
  vite: {
    plugins: [
      // ... your other plugins
      sitemapPlugin({
        baseUrl: 'https://your-domain.com',
        outputPath: "public/sitemap.xml",
        verbose: true,
      }),
    ],
  },
  // ...

2. Programmatic Usage

import { writeFileSync, mkdirSync, existsSync } from 'fs';
import { join } from 'path';
import { generateSitemap } from '@corentints/tanstack-router-sitemap';
import { routeTree } from './routeTree.gen'; // Your generated route tree

const sitemap = await generateSitemap(routeTree, {
  baseUrl: 'https://your-domain.com',
  defaultChangefreq: 'weekly',
  defaultPriority: 0.8,
});

// Ensure the public directory exists
const outputPath = 'public/sitemap.xml';
const outputDir = join(process.cwd(), 'public');
if (!existsSync(outputDir)) {
  mkdirSync(outputDir, { recursive: true });
}

// Write sitemap to file
writeFileSync(join(process.cwd(), outputPath), sitemap, 'utf8');
console.log(`✅ Sitemap saved to ${outputPath}`);

Configuration Options

SitemapOptions

Option	Type	Default	Description
baseUrl	string	Required	Base URL for your site (e.g., 'https://example.com')
defaultChangefreq	string	'weekly'	Default changefreq for all routes
defaultPriority	number	0.5	Default priority for all routes (0.0 to 1.0)
excludeRoutes	string[]	[]	Routes to exclude from sitemap (supports glob patterns)
routeOptions	Record<string, Partial<SitemapEntry>>	{}	Custom configurations per route
trailingSlash	boolean	false	Whether to include trailing slashes
lastmod	string	Current date	Custom lastmod date for all routes
prettyPrint	boolean	true	Pretty print the XML output
manualRoutes	() => Promise<ManualSitemapEntry[]> | ManualSitemapEntry[]	undefined	Function to generate manual/dynamic routes

SitemapPluginOptions (extends SitemapOptions)

Option	Type	Default	Description
outputPath	string	'public/sitemap.xml'	Output path for the sitemap.xml file
verbose	boolean	false	Whether to log sitemap generation info
routeTreePath	string	Auto-detected	Path to routeTree.gen.ts file
onBuildOnly	boolean	false	Only generate sitemap on build

Advanced Usage

Excluding Routes

sitemapPlugin({
  baseUrl: 'https://your-domain.com',
  excludeRoutes: [
    '/admin',          // Exclude specific route
    '/admin/*',        // Exclude all admin routes
    '/api/*',          // Exclude all API routes
    '/private-*',      // Exclude routes starting with 'private-'
  ],
});

Custom Route Configuration

sitemapPlugin({
  baseUrl: 'https://your-domain.com',
  routeOptions: {
    '/': {
      priority: 1.0,
      changefreq: 'daily',
    },
    '/blog': {
      priority: 0.8,
      changefreq: 'weekly',
    },
    '/about': {
      priority: 0.6,
      changefreq: 'monthly',
      lastmod: '2024-01-01T00:00:00.000Z',
    },
  },
});

Route Detection

The plugin automatically:

• ✅ Includes static routes (e.g., /about, /contact)
• ❌ Excludes dynamic routes (e.g., /users/$id, /posts/[slug])
• ❌ Excludes routes in your excludeRoutes configuration
• ✅ Processes nested route structures recursively

Example Output

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://your-domain.com/</loc>
    <lastmod>2024-01-15T12:00:00.000Z</lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://your-domain.com/about</loc>
    <lastmod>2024-01-15T12:00:00.000Z</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://your-domain.com/blog</loc>
    <lastmod>2024-01-15T12:00:00.000Z</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

Manual Routes for Dynamic Content

For dynamic routes like blog posts, articles, or other database-driven content, you can use the manualRoutes option:

manualRoutes: async () => {
  const [posts, products, events] = await Promise.all([
    fetchBlogPosts(),
    fetchProducts(),
    fetchEvents()
  ]);

  return [
    ...posts.map(post => ({
      location: `/blog/${post.slug}`,
      priority: 0.8,
      lastMod: post.publishedAt,
      changeFrequency: 'weekly' as const
    })),
    ...products.map(product => ({
      location: `/shop/${product.id}`,
      priority: 0.7,
      changeFrequency: 'monthly' as const
    })),
    ...events.map(event => ({
      location: `/events/${event.id}`,
      priority: 0.9,
      lastMod: event.updatedAt,
      changeFrequency: 'daily' as const
    }))
  ];
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Built with ❤️ for the TanStack community