0
# Data Types and Configuration
1

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

4
## Capabilities
5

6
### Core Sitemap Types
7

8
**Primary Sitemap URL Structure**
9

10
```typescript { .api }
11
/**
12
 * Core sitemap URL entry with all standard sitemap fields
13
 */
14
interface SitemapUrl {
15
  /** URL location (required) */
16
  loc: string;
17
  /** Last modification date */
18
  lastmod?: string | Date;
19
  /** How frequently the page is likely to change */
20
  changefreq?: Changefreq;
21
  /** Priority of this URL relative to other URLs on your site */
22
  priority?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
23
  /** Alternative language versions of this URL */
24
  alternatives?: AlternativeEntry[];
25
  /** Google News metadata for news articles */
26
  news?: GoogleNewsEntry;
27
  /** Associated images for this URL */
28
  images?: ImageEntry[];
29
  /** Associated videos for this URL */
30
  videos?: VideoEntry[];
31
  /** Internal flag for i18n transformation */
32
  _i18nTransform?: boolean;
33
  /** Internal sitemap name reference */
34
  _sitemap?: string;
35
}
36

37
/**
38
 * Input type for sitemap URLs - accepts either full object or string URL
39
 */
40
type SitemapUrlInput = SitemapUrl | string;
41

42
/**
43
 * Strict version with all optional properties required
44
 */
45
type SitemapStrict = Required<SitemapUrl>;
46

47
/**
48
 * Valid change frequency values
49
 */
50
type Changefreq = 
51
  | 'always' 
52
  | 'hourly' 
53
  | 'daily' 
54
  | 'weekly' 
55
  | 'monthly' 
56
  | 'yearly' 
57
  | 'never';
58
```
59

60
**Resolved URL Type (Internal)**
61

62
```typescript { .api }
63
/**
64
 * Internal resolved sitemap URL with computed properties
65
 */
66
interface ResolvedSitemapUrl extends Omit<SitemapUrl, 'url'>, Required<Pick<SitemapUrl, 'loc'>> {
67
  /** Internal unique key */
68
  _key: string;
69
  /** Parsed URL components */
70
  _path: ParsedURL;
71
  /** Relative location path */
72
  _relativeLoc: string;
73
  /** Whether URL is absolute */
74
  _abs: boolean;
75
}
76
```
77

78
### Sitemap Definition and Configuration
79

80
**Base Sitemap Definition**
81

82
```typescript { .api }
83
/**
84
 * Base configuration for individual sitemaps
85
 */
86
interface SitemapDefinition {
87
  /** URL include patterns for filtering */
88
  include?: FilterInput[];
89
  /** URL exclude patterns for filtering */
90
  exclude?: FilterInput[];
91
  /** Whether to include global app sources */
92
  includeAppSources?: boolean;
93
  /** Sitemap filename */
94
  sitemapName: string;
95
  /** URL collection - can be static array or dynamic function */
96
  urls?: MaybeFunction<MaybePromise<SitemapUrlInput[]>>;
97
  /** Default properties applied to all URLs */
98
  defaults?: Omit<SitemapUrl, 'loc'>;
99
  /** Additional URL sources */
100
  sources?: SitemapSourceInput[];
101
  /** Enable chunking configuration */
102
  chunks?: boolean | number;
103
  /** Maximum URLs per chunk */
104
  chunkSize?: number;
105
  /** Internal route reference */
106
  _route?: string;
107
  /** Internal chunking flag */
108
  _isChunking?: boolean;
109
  /** Internal chunk size */
110
  _chunkSize?: number;
111
  /** Internal chunk count */
112
  _chunkCount?: number;
113
}
114
```
115

116
**Filter Input Types**
117

118
```typescript { .api }
119
/**
120
 * Filter patterns for URL matching
121
 */
122
type FilterInput = string | RegExp | {
123
  regex: string;
124
};
125
```
126

127
**Utility Types**
128

129
```typescript { .api }
130
/**
131
 * Value that can be a direct value or function returning the value
132
 */
133
type MaybeFunction<T> = T | (() => T);
134

135
/**
136
 * Value that can be synchronous or asynchronous
137
 */
138
type MaybePromise<T> = T | Promise<T>;
139
```
140

141
### URL Source Configuration
142

143
**Source Input Types**
144

145
```typescript { .api }
146
/**
147
 * Input types for URL sources
148
 */
149
type SitemapSourceInput = 
150
  | string 
151
  | [string, FetchOptions] 
152
  | SitemapSourceBase 
153
  | SitemapSourceResolved;
154

155
/**
156
 * Base URL source configuration
157
 */
158
interface SitemapSourceBase {
159
  /** Source metadata and documentation */
160
  context: {
161
    name: string;
162
    description?: string;
163
    tips?: string[];
164
  };
165
  /** Fetch configuration for remote sources */
166
  fetch?: string | [string, FetchOptions];
167
  /** Static URLs provided by this source */
168
  urls?: SitemapUrlInput[];
169
  /** Source classification */
170
  sourceType?: 'app' | 'user';
171
}
172

173
/**
174
 * Resolved URL source with runtime data
175
 */
176
interface SitemapSourceResolved extends Omit<SitemapSourceBase, 'urls'> {
177
  /** Resolved URLs (required after resolution) */
178
  urls: SitemapUrlInput[];
179
  /** Any errors encountered during resolution */
180
  error?: any;
181
  /** Time taken to resolve source in milliseconds */
182
  timeTakenMs?: number;
183
  /** Whether source resolution failed */
184
  _isFailure?: boolean;
185
}
186

187
/**
188
 * App source context types
189
 */
190
type AppSourceContext = 
191
  | 'nuxt:pages' 
192
  | 'nuxt:prerender' 
193
  | 'nuxt:route-rules' 
194
  | '@nuxtjs/i18n:pages' 
195
  | '@nuxt/content:document-driven';
196
```
197

198
### Multiple Sitemaps Configuration
199

200
**Multi-Sitemap Types**
201

202
```typescript { .api }
203
/**
204
 * Configuration for multiple sitemaps
205
 */
206
interface MultiSitemapEntry {
207
  [key: string]: Partial<SitemapDefinition>;
208
}
209

210
/**
211
 * Index sitemap configuration
212
 */
213
interface IndexSitemapRemotes {
214
  index?: (string | SitemapIndexEntry)[];
215
}
216

217
/**
218
 * Combined multi-sitemap input type
219
 */
220
type MultiSitemapsInput = Partial<MultiSitemapEntry> & Partial<IndexSitemapRemotes>;
221

222
/**
223
 * Sitemap index entry
224
 */
225
interface SitemapIndexEntry {
226
  /** Sitemap URL */
227
  sitemap: string;
228
  /** Last modification date of the sitemap */
229
  lastmod?: string;
230
  /** Internal sitemap name reference */
231
  _sitemapName?: string;
232
}
233
```
234

235
### Media and Extension Types
236

237
**Image Metadata**
238

239
```typescript { .api }
240
/**
241
 * Image entry for sitemap image extensions
242
 */
243
interface ImageEntry {
244
  /** Image URL location */
245
  loc: string | URL;
246
  /** Image caption text */
247
  caption?: string;
248
  /** Geographic location of the image */
249
  geoLocation?: string;
250
  /** Image title */
251
  title?: string;
252
  /** License URL for the image */
253
  license?: string | URL;
254
}
255
```
256

257
**Video Metadata**
258

259
```typescript { .api }
260
/**
261
 * Video entry for sitemap video extensions
262
 */
263
interface VideoEntry {
264
  /** Video title (required) */
265
  title: string;
266
  /** Video thumbnail URL (required) */
267
  thumbnail_loc: string | URL;
268
  /** Video description (required) */
269
  description: string;
270
  /** Direct video content URL */
271
  content_loc?: string | URL;
272
  /** Video player page URL */
273
  player_loc?: string | URL;
274
  /** Video duration in seconds */
275
  duration?: number;
276
  /** Video expiration date */
277
  expiration_date?: Date | string;
278
  /** Video rating (0.0 to 5.0) */
279
  rating?: number;
280
  /** View count */
281
  view_count?: number;
282
  /** Publication date */
283
  publication_date?: Date | string;
284
  /** Family-friendly content flag */
285
  family_friendly?: 'yes' | 'no' | boolean;
286
  /** Geographic restrictions */
287
  restriction?: Restriction;
288
  /** Platform restrictions */
289
  platform?: Platform;
290
  /** Pricing information */
291
  price?: PriceEntry[];
292
  /** Subscription requirement */
293
  requires_subscription?: 'yes' | 'no' | boolean;
294
  /** Uploader information */
295
  uploader?: {
296
    uploader: string;
297
    info?: string | URL;
298
  };
299
  /** Live content indicator */
300
  live?: 'yes' | 'no' | boolean;
301
  /** Content tags */
302
  tag?: string | string[];
303
}
304

305
/**
306
 * Geographic restriction configuration
307
 */
308
interface Restriction {
309
  relationship: 'allow' | 'deny';
310
  restriction: string;
311
}
312

313
/**
314
 * Platform restriction configuration
315
 */
316
interface Platform {
317
  relationship: 'allow' | 'deny';
318
  platform: string;
319
}
320

321
/**
322
 * Video pricing information
323
 */
324
interface PriceEntry {
325
  price?: number | string;
326
  currency?: string;
327
  type?: 'rent' | 'purchase' | 'package' | 'subscription';
328
}
329
```
330

331
**Alternative URL Structure**
332

333
```typescript { .api }
334
/**
335
 * Alternative URL entry for i18n support
336
 */
337
interface AlternativeEntry {
338
  /** Language/locale code (hreflang attribute) */
339
  hreflang: string;
340
  /** Alternative URL */
341
  href: string | URL;
342
}
343
```
344

345
**Google News Metadata**
346

347
```typescript { .api }
348
/**
349
 * Google News metadata for news articles
350
 */
351
interface GoogleNewsEntry {
352
  /** News article title */
353
  title: string;
354
  /** Article publication date in W3C format */
355
  publication_date: Date | string;
356
  /** Publication information */
357
  publication: {
358
    /** Publication name as it appears on news.google.com */
359
    name: string;
360
    /** Publication language (ISO 639 code) */
361
    language: string;
362
  };
363
}
364
```
365

366
### Runtime and Hook Context Types
367

368
**Runtime Configuration**
369

370
```typescript { .api }
371
/**
372
 * Runtime configuration available in server context
373
 */
374
interface ModuleRuntimeConfig extends Pick<
375
  ModuleOptions, 
376
  | 'sitemapsPathPrefix' 
377
  | 'cacheMaxAgeSeconds' 
378
  | 'sitemapName' 
379
  | 'excludeAppSources' 
380
  | 'sortEntries' 
381
  | 'defaultSitemapsChunkSize' 
382
  | 'xslColumns' 
383
  | 'xslTips' 
384
  | 'debug' 
385
  | 'discoverImages' 
386
  | 'discoverVideos' 
387
  | 'autoLastmod' 
388
  | 'xsl' 
389
  | 'credits' 
390
  | 'minify'
391
> {
392
  /** Module version */
393
  version: string;
394
  /** Whether Nuxt Content document-driven mode is enabled */
395
  isNuxtContentDocumentDriven: boolean;
396
  /** Sitemap definitions and index configuration */
397
  sitemaps: { 
398
    index?: Pick<SitemapDefinition, 'sitemapName' | '_route'> & { 
399
      sitemaps: SitemapIndexEntry[] 
400
    } 
401
  } & Record<string, Omit<SitemapDefinition, 'urls'> & { _hasSourceChunk?: boolean }>;
402
  /** Auto i18n configuration */
403
  autoI18n?: AutoI18nConfig;
404
  /** Whether multiple sitemaps are enabled */
405
  isMultiSitemap: boolean;
406
  /** Whether i18n URL mapping is enabled */
407
  isI18nMapped: boolean;
408
}
409
```
410

411
**Hook Context Types**
412

413
```typescript { .api }
414
/**
415
 * Base hook context with H3 event
416
 */
417
interface NitroBaseHook {
418
  event: H3Event;
419
}
420

421
/**
422
 * Context for sitemap index render hooks
423
 */
424
interface SitemapIndexRenderCtx extends NitroBaseHook {
425
  sitemaps: SitemapIndexEntry[];
426
}
427

428
/**
429
 * Context for individual sitemap render hooks
430
 */
431
interface SitemapRenderCtx extends NitroBaseHook {
432
  sitemapName: string;
433
  urls: ResolvedSitemapUrl[];
434
}
435

436
/**
437
 * Context for sitemap input processing hooks
438
 */
439
interface SitemapInputCtx extends NitroBaseHook {
440
  sitemapName: string;
441
  urls: SitemapUrlInput[];
442
}
443

444
/**
445
 * Context for sitemap output hooks
446
 */
447
interface SitemapOutputHookCtx extends NitroBaseHook {
448
  sitemapName: string;
449
  sitemap: string;
450
}
451

452
/**
453
 * Context for sitemap sources hooks
454
 */
455
interface SitemapSourcesHookCtx extends NitroBaseHook {
456
  sitemapName: string;
457
  sources: (SitemapSourceBase | SitemapSourceResolved)[];
458
}
459
```
460

461
### i18n Integration Types
462

463
**i18n Configuration**
464

465
```typescript { .api }
466
/**
467
 * Auto i18n configuration for multi-language sitemaps
468
 */
469
interface AutoI18nConfig {
470
  /** Whether different domains are used for locales */
471
  differentDomains?: boolean;
472
  /** Locale configurations with sitemap metadata */
473
  locales: (LocaleObject & { 
474
    _sitemap: string; 
475
    _hreflang: string; 
476
  })[];
477
  /** Default locale code */
478
  defaultLocale: string;
479
  /** URL generation strategy */
480
  strategy: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
481
  /** Page-specific translations */
482
  pages?: Record<string, Record<string, string | false>>;
483
}
484

485
/**
486
 * Locale object configuration
487
 */
488
interface LocaleObject extends Record<string, any> {
489
  /** Locale code */
490
  code: string;
491
  /** Locale display name */
492
  name?: string;
493
  /** Text direction */
494
  dir?: 'ltr' | 'rtl' | 'auto';
495
  /** Primary domain for this locale */
496
  domain?: string;
497
  /** Multiple domains for this locale */
498
  domains?: string[];
499
  /** Default locale for specified domains */
500
  defaultForDomains?: string[];
501
  /** Language file configuration */
502
  file?: string | {
503
    path: string;
504
    cache?: boolean;
505
  };
506
  /** Multiple language files */
507
  files?: string[] | {
508
    path: string;
509
    cache?: boolean;
510
  }[];
511
  /** Whether this is a catch-all locale */
512
  isCatchallLocale?: boolean;
513
  /** @deprecated - use language instead */
514
  iso?: string;
515
  /** Language code */
516
  language?: string;
517
}
518

519
/**
520
 * Combined i18n integration options
521
 */
522
type I18nIntegrationOptions = NuxtI18nOptions & NuxtI18nMicro;
523

524
/**
525
 * Nuxt i18n micro integration
526
 */
527
interface NuxtI18nMicro {
528
  includeDefaultLocaleRoute?: boolean;
529
}
530
```
531

532
### Utility and Helper Types
533

534
**URL Resolution Utilities**
535

536
```typescript { .api }
537
/**
538
 * Nitro URL resolvers for server context
539
 */
540
interface NitroUrlResolvers {
541
  event: H3Event;
542
  canonicalUrlResolver: (path: string) => string;
543
  relativeBaseUrlResolver: (path: string) => string;
544
  fixSlashes: (path: string) => string;
545
}
546
```
547

548
**XSL Configuration**
549

550
```typescript { .api }
551
/**
552
 * XSL column configuration for sitemap styling
553
 */
554
interface XslColumn {
555
  label: string;
556
  width: `${string}%`;
557
  select?: string;
558
}
559
```
560

561
**Usage Examples:**
562

563
```typescript
564
// Type-safe sitemap URL creation
565
const sitemapUrl: SitemapUrl = {
566
  loc: '/blog/post-1',
567
  lastmod: new Date(),
568
  changefreq: 'weekly',
569
  priority: 0.8,
570
  images: [{
571
    loc: '/images/blog/post-1-hero.jpg',
572
    caption: 'Blog post hero image',
573
    title: 'How to Use TypeScript'
574
  }],
575
  alternatives: [{
576
    hreflang: 'es',
577
    href: '/es/blog/post-1'
578
  }]
579
};
580

581
// Multi-sitemap configuration
582
const multiSitemapConfig: MultiSitemapsInput = {
583
  posts: {
584
    includeAppSources: true,
585
    include: ['/blog/**', '/news/**'],
586
    defaults: {
587
      changefreq: 'weekly',
588
      priority: 0.7
589
    }
590
  },
591
  pages: {
592
    includeAppSources: true,
593
    exclude: ['/blog/**', '/news/**'],
594
    defaults: {
595
      changefreq: 'monthly',
596
      priority: 0.5
597
    }
598
  }
599
};
600

601
// Source configuration with type safety
602
const dynamicSource: SitemapSourceBase = {
603
  context: {
604
    name: 'Product Pages',
605
    description: 'Dynamic product URLs from database',
606
    tips: ['Updates every hour', 'Includes product images']
607
  },
608
  fetch: ['/api/products-sitemap', { 
609
    headers: { 'Accept': 'application/json' } 
610
  }],
611
  sourceType: 'user'
612
};
613

614
// i18n configuration
615
const i18nConfig: AutoI18nConfig = {
616
  differentDomains: false,
617
  locales: [
618
    { 
619
      code: 'en', 
620
      _sitemap: 'en', 
621
      _hreflang: 'en',
622
      name: 'English'
623
    },
624
    { 
625
      code: 'es', 
626
      _sitemap: 'es', 
627
      _hreflang: 'es',
628
      name: 'Español'
629
    }
630
  ],
631
  defaultLocale: 'en',
632
  strategy: 'prefix_except_default'
633
};
634
```