vite-ssg-sitemap

0.10.0 verified Mon Apr 27 auth: no javascript

A sitemap generator plugin for Vite projects using vite-ssg, built on top of sitemap-ts. Version 0.10.0, actively maintained. It automates sitemap.xml and robots.txt generation during static site builds. Key differentiators: tight integration with vite-ssg's lifecycle (onFinished hook), supports dynamic routes, route-level overrides for change frequency/priority/lastmod, i18n alternate links, and customizable output options. Simpler than full-featured sitemap libraries but specifically designed for the vite-ssg ecosystem.

Common errors

error TypeError: generateSitemap is not a function ↓

cause Importing with named import instead of default import.

fix

Use import generateSitemap from 'vite-ssg-sitemap' (default import).

error Error: No routes provided: sitemap will be empty ↓

cause No `dynamicRoutes` passed and no automatic route detection (since v0.6.0).

fix

Pass an array of route paths to dynamicRoutes in options.

error Error: Cannot find module 'sitemap-ts' ↓

cause Missing peer dependency sitemap-ts.

fix

Run npm install -D sitemap-ts.

error Error: XML parsing failed: Invalid tag name at line X ↓

cause Route path contains invalid characters (e.g., spaces, reserved XML characters).

fix

Ensure all route strings are URL-encoded or sanitized.

Warnings

gotcha generateSitemap is a default export, not a named export. Importing with destructured { generateSitemap } yields undefined. ↓

fix Use `import generateSitemap from 'vite-ssg-sitemap'` (no braces).

gotcha The `hostname` option defaults to 'http://localhost/', which may produce invalid sitemap URLs in production. Always set a proper hostname. ↓

fix Pass `hostname: 'https://yoursite.com'` in options.

breaking In v0.6.0, the `i18n` option was refactored. The `defaultLanguage` property was added and `languages` is now required if using i18n. Old `lang` property removed. ↓

fix Update your i18n config to { defaultLanguage?, languages: string[] }.

gotcha The `outDir` is relative to the project root, not the Vite build output config. If you customize Vite's build.outDir, you must set this option accordingly. ↓

fix Set `outDir` to match your Vite build output directory (default 'dist').

deprecated Version 0.6.0 removed automatic route detection from vite-ssg. You must now pass routes via `dynamicRoutes`; the plugin no longer reads the vue-router routes. ↓

fix Manually collect routes and pass to `dynamicRoutes`. See README for example.

Install

npm install vite-ssg-sitemap

yarn add vite-ssg-sitemap

pnpm add vite-ssg-sitemap

Imports

generateSitemap

wrong

import { generateSitemap } from 'vite-ssg-sitemap'

correct

import generateSitemap from 'vite-ssg-sitemap'

Default export only. Named import will result in undefined.

generateSitemap

wrong

const { generateSitemap } = require('vite-ssg-sitemap')

correct

const generateSitemap = require('vite-ssg-sitemap')

CJS require returns default as module.exports. Destructuring fails.

generateSitemap type

wrong

import { RouteOptionMap } from 'vite-ssg-sitemap'

correct

import type { RouteOptionMap, SitemapOption } from 'vite-ssg-sitemap'

Types are not runtime values; use type import for TypeScript.

Quickstart

Example of using generateSitemap in vite.config.ts with i18n, dynamic routes, exclusions, and readable XML.

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import generateSitemap from 'vite-ssg-sitemap'

export default defineConfig({
  plugins: [vue()],
  ssgOptions: {
    onFinished() {
      generateSitemap({
        hostname: 'https://example.com',
        dynamicRoutes: ['/about', '/contact'],
        exclude: ['/admin'],
        readable: true,
        i18n: {
          defaultLanguage: 'en',
          languages: ['fr', 'de'],
          strategy: 'prefix'
        }
      })
    }
  }
})