0
# @nuxtjs/sitemap
1

2
@nuxtjs/sitemap is a comprehensive Nuxt.js module that provides powerfully flexible XML sitemap generation capabilities for Nuxt applications. It offers single and multiple sitemap support, automatic URL discovery, image and video discovery, lastmod detection, SWR caching, i18n integration, and extensive customization options for SEO-compliant XML sitemaps.
3

4
## Package Information
5

6
- **Package Name**: @nuxtjs/sitemap
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npx nuxi@latest module add sitemap`
10

11
## Core Imports
12

13
```typescript
14
// Main module and types
15
import type { ModuleOptions } from '@nuxtjs/sitemap';
16

17
// Content integration
18
import { schema, asSitemapCollection } from '@nuxtjs/sitemap/content';
19

20
// Utilities
21
import { parseSitemapXml, parseHtmlExtractSitemapMeta } from '@nuxtjs/sitemap/utils';
22
```
23

24
**Server-only imports (available only in server context):**
25

26
```typescript
27
// Server composables (only available in Nuxt server context)
28
import { asSitemapUrl, defineSitemapEventHandler } from '#sitemap/server/composables';
29
```
30

31
## Basic Usage
32

33
```typescript
34
// nuxt.config.ts
35
export default defineNuxtConfig({
36
  modules: ['@nuxtjs/sitemap'],
37
  sitemap: {
38
    hostname: 'https://example.com',
39
    gzip: true,
40
    urls: [
41
      '/special-page',
42
      {
43
        loc: '/priority-page',
44
        lastmod: new Date(),
45
        changefreq: 'weekly',
46
        priority: 0.8
47
      }
48
    ]
49
  }
50
})
51
```
52

53
## Architecture
54

55
@nuxtjs/sitemap is built around several key components:
56

57
- **Module System**: Core Nuxt module providing automatic route discovery and sitemap generation
58
- **Configuration Engine**: Comprehensive options system for sitemap behavior, chunking, and filtering
59
- **Multi-sitemap Support**: Ability to generate multiple categorized sitemaps with index files
60
- **Content Integration**: Deep integration with Nuxt Content for automatic content-driven sitemaps
61
- **Server Runtime**: Server-side composables and utilities for dynamic sitemap generation
62
- **Type System**: Complete TypeScript type definitions for all APIs and configuration options
63
- **Parsing Utilities**: Tools for parsing existing XML sitemaps and extracting metadata from HTML
64

65
## Capabilities
66

67
### Module Configuration
68

69
Core Nuxt module setup and comprehensive configuration options for sitemap generation, including single/multiple sitemap support, caching, filtering, and i18n integration.
70

71
```typescript { .api }
72
interface ModuleOptions extends SitemapDefinition {
73
  enabled: boolean;
74
  debug: boolean;
75
  minify: boolean;
76
  credits: boolean;
77
  autoLastmod: boolean;
78
  excludeAppSources: true | AppSourceContext[];
79
  sortEntries: boolean;
80
  discoverImages: boolean;
81
  discoverVideos: boolean;
82
  defaultSitemapsChunkSize: number | false;
83
  sitemaps?: boolean | MultiSitemapsInput;
84
  sitemapsPathPrefix: string | false;
85
  appendSitemaps?: (string | SitemapIndexEntry)[];
86
  xsl: string | false;
87
  xslTips: boolean;
88
  xslColumns?: XslColumn[];
89
  cacheMaxAgeSeconds: number | false;
90
  runtimeCacheStorage: boolean | (Record<string, any> & { driver: string });
91
  autoI18n?: boolean | AutoI18nConfig;
92
  strictNuxtContentPaths: boolean;
93
  experimentalWarmUp?: boolean;
94
  experimentalCompression?: boolean;
95
}
96
```
97

98
[Module Configuration](./module-configuration.md)
99

100
### Content Integration
101

102
Nuxt Content integration with sitemap-specific schema validation and collection enhancement for seamless content-driven sitemap generation.
103

104
```typescript { .api }
105
function asSitemapCollection<T extends ZodRawShape>(
106
  collection: Collection<T>
107
): Collection<T>;
108

109
const schema: ZodObject<{
110
  sitemap: ZodObject<SitemapContentFields>
111
}>;
112
```
113

114
[Content Integration](./content-integration.md)
115

116
### Server Composables
117

118
Server-side composables and utilities for runtime sitemap generation, URL processing, and event handler creation within the Nuxt server context.
119

120
```typescript { .api }
121
function asSitemapUrl(
122
  url: SitemapUrlInput | Record<string, any>
123
): SitemapUrlInput;
124

125
const defineSitemapEventHandler: typeof defineEventHandler<
126
  EventHandlerRequest, 
127
  EventHandlerResponse<SitemapUrlInput[]>
128
>;
129
```
130

131
[Server Composables](./server-composables.md)
132

133
### XML and HTML Utilities
134

135
Utility functions for parsing existing XML sitemaps and extracting sitemap metadata from HTML documents for analysis and integration purposes.
136

137
```typescript { .api }
138
function parseSitemapXml(xml: string): Promise<SitemapParseResult>;
139

140
function parseHtmlExtractSitemapMeta(
141
  html: string, 
142
  options?: {
143
    images?: boolean;
144
    videos?: boolean;
145
    lastmod?: boolean;
146
    alternatives?: boolean;
147
    resolveUrl?: (s: string) => string;
148
  }
149
): SitemapUrl[];
150

151
interface SitemapParseResult {
152
  urls: SitemapUrlInput[];
153
  warnings: SitemapWarning[];
154
}
155

156
interface SitemapWarning {
157
  type: 'validation';
158
  message: string;
159
  context?: {
160
    url?: string;
161
    field?: string;
162
    value?: unknown;
163
  };
164
}
165
```
166

167
[XML and HTML Utilities](./xml-html-utilities.md)
168

169
### Data Types and Configuration
170

171
Comprehensive type system covering sitemap entries, validation schemas, configuration interfaces, and runtime context objects for full type safety.
172

173
```typescript { .api }
174
interface SitemapUrl {
175
  loc: string;
176
  lastmod?: string | Date;
177
  changefreq?: Changefreq;
178
  priority?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
179
  alternatives?: AlternativeEntry[];
180
  images?: ImageEntry[];
181
  videos?: VideoEntry[];
182
}
183

184
interface SitemapDefinition {
185
  include?: FilterInput[];
186
  exclude?: FilterInput[];
187
  sitemapName: string;
188
  urls?: MaybeFunction<MaybePromise<SitemapUrlInput[]>>;
189
  sources?: SitemapSourceInput[];
190
}
191
```
192

193
[Data Types and Configuration](./data-types-configuration.md)