UNPKG

18.4 kBTypeScriptView Raw
1import type { AlternateURLs, Languages, ResolvedAlternateURLs } from './alternative-urls-types';
2import type { AppleWebApp, AppLinks, Facebook, FormatDetection, ItunesApp, ResolvedAppleWebApp, ResolvedAppLinks, ResolvedFacebook, ViewportLayout } from './extra-types';
3import type { DeprecatedMetadataFields, AbsoluteTemplateString, Author, ColorSchemeEnum, Icon, Icons, IconURL, ReferrerEnum, ResolvedIcons, ResolvedVerification, Robots, ResolvedRobots, TemplateString, Verification, ThemeColorDescriptor, Videos } from './metadata-types';
4import type { Manifest as ManifestFile } from './manifest-types';
5import type { OpenGraph, ResolvedOpenGraph } from './opengraph-types';
6import type { ResolvedTwitterMetadata, Twitter } from './twitter-types';
7/**
8 * Metadata interface to describe all the metadata fields that can be set in a document.
9 * @interface
10 */
11interface Metadata extends DeprecatedMetadataFields {
12 /**
13 * The base path and origin for absolute urls for various metadata links such as OpenGraph images.
14 */
15 metadataBase?: null | URL | undefined;
16 /**
17 * The document title.
18 * @example
19 * ```tsx
20 * "My Blog"
21 * <title>My Blog</title>
22 *
23 * { default: "Dashboard", template: "%s | My Website" }
24 * <title>Dashboard | My Website</title>
25 *
26 * { absolute: "My Blog", template: "%s | My Website" }
27 * <title>My Blog</title>
28 * ```
29 */
30 title?: null | string | TemplateString | undefined;
31 /**
32 * The document description, and optionally the OpenGraph and twitter descriptions.
33 * @example
34 * ```tsx
35 * "My Blog Description"
36 * <meta name="description" content="My Blog Description" />
37 * ```
38 */
39 description?: null | string | undefined;
40 /**
41 * The application name.
42 * @example
43 * ```tsx
44 * "My Blog"
45 * <meta name="application-name" content="My Blog" />
46 * ```
47 */
48 applicationName?: null | string | undefined;
49 /**
50 * The authors of the document.
51 * @example
52 * ```tsx
53 * [{ name: "Next.js Team", url: "https://nextjs.org" }]
54 *
55 * <meta name="author" content="Next.js Team" />
56 * <link rel="author" href="https://nextjs.org" />
57 * ```
58 */
59 authors?: null | Author | Array<Author> | undefined;
60 /**
61 * The generator used for the document.
62 * @example
63 * ```tsx
64 * "Next.js"
65 *
66 * <meta name="generator" content="Next.js" />
67 * ```
68 */
69 generator?: null | string | undefined;
70 /**
71 * The keywords for the document. If an array is provided, it will be flattened into a single tag with comma separation.
72 * @example
73 * ```tsx
74 * "nextjs, react, blog"
75 * <meta name="keywords" content="nextjs, react, blog" />
76 *
77 * ["react", "server components"]
78 * <meta name="keywords" content="react, server components" />
79 * ```
80 */
81 keywords?: null | string | Array<string> | undefined;
82 /**
83 * The referrer setting for the document.
84 * @example
85 * ```tsx
86 * "origin"
87 * <meta name="referrer" content="origin" />
88 * ```
89 */
90 referrer?: null | ReferrerEnum | undefined;
91 /**
92 * The theme color for the document.
93 * @deprecated Use `export const viewport: Viewport = { ... }` instead.
94 * @see https://nextjs.org/docs/app/api-reference/functions/generate-viewport#the-viewport-object
95 * @example
96 * ```tsx
97 * "#000000"
98 * <meta name="theme-color" content="#000000" />
99 *
100 * { media: "(prefers-color-scheme: dark)", color: "#000000" }
101 * <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#000000" />
102 *
103 * [
104 * { media: "(prefers-color-scheme: dark)", color: "#000000" },
105 * { media: "(prefers-color-scheme: light)", color: "#ffffff" }
106 * ]
107 * <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#000000" />
108 * <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
109 * ```
110 */
111 themeColor?: null | string | ThemeColorDescriptor | ThemeColorDescriptor[] | undefined;
112 /**
113 * The color scheme for the document.
114 * @deprecated Use `export const viewport: Viewport = { ... }` instead.
115 * @see https://nextjs.org/docs/app/api-reference/functions/generate-viewport#the-viewport-object
116 * @example
117 * ```tsx
118 * "dark"
119 * <meta name="color-scheme" content="dark" />
120 * ```
121 */
122 colorScheme?: null | ColorSchemeEnum | undefined;
123 /**
124 * The viewport setting for the document.
125 * @deprecated Use `export const viewport: Viewport = { ... }` instead.
126 * @see https://nextjs.org/docs/app/api-reference/functions/generate-viewport#the-viewport-object
127 * @example
128 * ```tsx
129 * { width: "device-width", initialScale: 1 }
130 * <meta name="viewport" content="width=device-width, initial-scale=1" />
131 * ```
132 */
133 viewport?: null | string | ViewportLayout | undefined;
134 /**
135 * The creator of the document.
136 * @example
137 * ```tsx
138 * "Next.js Team"
139 * <meta name="creator" content="Next.js Team" />
140 * ```
141 */
142 creator?: null | string | undefined;
143 /**
144 * The publisher of the document.
145 * @example
146 *
147 * ```tsx
148 * "Vercel"
149 * <meta name="publisher" content="Vercel" />
150 * ```
151 */
152 publisher?: null | string | undefined;
153 /**
154 * The robots setting for the document.
155 *
156 * @see https://developer.mozilla.org/docs/Glossary/Robots.txt
157 * @example
158 * ```tsx
159 * "index, follow"
160 * <meta name="robots" content="index, follow" />
161 *
162 * { index: false, follow: false }
163 * <meta name="robots" content="noindex, nofollow" />
164 * ```
165 */
166 robots?: null | string | Robots | undefined;
167 /**
168 * The canonical and alternate URLs for the document.
169 * @example
170 * ```tsx
171 * { canonical: "https://example.com" }
172 * <link rel="canonical" href="https://example.com" />
173 *
174 * { canonical: "https://example.com", hreflang: { "en-US": "https://example.com/en-US" } }
175 * <link rel="canonical" href="https://example.com" />
176 * <link rel="alternate" href="https://example.com/en-US" hreflang="en-US" />
177 * ```
178 *
179 * Multiple titles example for alternate URLs except `canonical`:
180 * ```tsx
181 * {
182 * canonical: "https://example.com",
183 * types: {
184 * 'application/rss+xml': [
185 * { url: 'blog.rss', title: 'rss' },
186 * { url: 'blog/js.rss', title: 'js title' },
187 * ],
188 * },
189 * }
190 * <link rel="canonical" href="https://example.com" />
191 * <link rel="alternate" href="https://example.com/blog.rss" type="application/rss+xml" title="rss" />
192 * <link rel="alternate" href="https://example.com/blog/js.rss" type="application/rss+xml" title="js title" />
193 * ```
194 */
195 alternates?: null | AlternateURLs | undefined;
196 /**
197 * The icons for the document. Defaults to rel="icon".
198 *
199 * @see https://developer.mozilla.org/docs/Web/HTML/Attributes/rel#attr-icon
200 * @example
201 * ```tsx
202 * "https://example.com/icon.png"
203 * <link rel="icon" href="https://example.com/icon.png" />
204 *
205 * { icon: "https://example.com/icon.png", apple: "https://example.com/apple-icon.png" }
206 * <link rel="icon" href="https://example.com/icon.png" />
207 * <link rel="apple-touch-icon" href="https://example.com/apple-icon.png" />
208 *
209 * [{ rel: "icon", url: "https://example.com/icon.png" }, { rel: "apple-touch-icon", url: "https://example.com/apple-icon.png" }]
210 * <link rel="icon" href="https://example.com/icon.png" />
211 * <link rel="apple-touch-icon" href="https://example.com/apple-icon.png" />
212 * ```
213 */
214 icons?: null | IconURL | Array<Icon> | Icons | undefined;
215 /**
216 * A web application manifest, as defined in the Web Application Manifest specification.
217 *
218 * @see https://developer.mozilla.org/docs/Web/Manifest
219 * @example
220 * ```tsx
221 * "https://example.com/manifest.json"
222 * <link rel="manifest" href="https://example.com/manifest.json" />
223 * ```
224 *
225 */
226 manifest?: null | string | URL | undefined;
227 /**
228 * The Open Graph metadata for the document.
229 *
230 * @see https://ogp.me
231 * @example
232 * ```tsx
233 * {
234 * type: "website",
235 * url: "https://example.com",
236 * title: "My Website",
237 * description: "My Website Description",
238 * siteName: "My Website",
239 * images: [{
240 * url: "https://example.com/og.png",
241 * }],
242 * }
243 *
244 * <meta property="og:type" content="website" />
245 * <meta property="og:url" content="https://example.com" />
246 * <meta property="og:site_name" content="My Website" />
247 * <meta property="og:title" content="My Website" />
248 * <meta property="og:description" content="My Website Description" />
249 * <meta property="og:image" content="https://example.com/og.png" />
250 * ```
251 */
252 openGraph?: null | OpenGraph | undefined;
253 /**
254 * The Twitter metadata for the document.
255 * @example
256 * ```tsx
257 * { card: "summary_large_image", site: "@site", creator: "@creator", images: "https://example.com/og.png" }
258 *
259 * <meta name="twitter:card" content="summary_large_image" />
260 * <meta name="twitter:site" content="@site" />
261 * <meta name="twitter:creator" content="@creator" />
262 * <meta name="twitter:title" content="My Website" />
263 * <meta name="twitter:description" content="My Website Description" />
264 * <meta name="twitter:image" content="https://example.com/og.png" />
265 * ```
266 *
267 */
268 twitter?: null | Twitter | undefined;
269 /**
270 * The Facebook metadata for the document.
271 * You can specify either appId or admins, but not both.
272 * @example
273 * ```tsx
274 * { appId: "12345678" }
275 *
276 * <meta property="fb:app_id" content="12345678" />
277 * ```
278 *
279 * @example
280 * ```tsx
281 * { admins: ["12345678"] }
282 *
283 * <meta property="fb:admins" content="12345678" />
284 * ```
285 */
286 facebook?: null | Facebook | undefined;
287 /**
288 * The common verification tokens for the document.
289 * @example
290 * ```tsx
291 * { verification: { google: "1234567890", yandex: "1234567890", "me": "1234567890" } }
292 * <meta name="google-site-verification" content="1234567890" />
293 * <meta name="yandex-verification" content="1234567890" />
294 * <meta name="me" content="@me" />
295 * ```
296 */
297 verification?: Verification | undefined;
298 /**
299 * The Apple web app metadata for the document.
300 *
301 * @see https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html
302 * @example
303 * ```tsx
304 * { capable: true, title: "My Website", statusBarStyle: "black-translucent" }
305 * <meta name="mobile-web-app-capable" content="yes" />
306 * <meta name="apple-mobile-web-app-title" content="My Website" />
307 * <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
308 * ```
309 *
310 */
311 appleWebApp?: null | boolean | AppleWebApp | undefined;
312 /**
313 * Indicates if devices should try to interpret various formats and make actionable links out of them. For example it controles
314 * if telephone numbers on mobile that can be clicked to dial or not.
315 * @example
316 * ```tsx
317 * { telephone: false }
318 * <meta name="format-detection" content="telephone=no" />
319 * ```
320 *
321 */
322 formatDetection?: null | FormatDetection | undefined;
323 /**
324 * The metadata for the iTunes App.
325 * It adds the `name="apple-itunes-app"` meta tag.
326 *
327 * @example
328 * ```tsx
329 * { app: { id: "123456789", affiliateData: "123456789", appArguments: "123456789" } }
330 * <meta name="apple-itunes-app" content="app-id=123456789, affiliate-data=123456789, app-arguments=123456789" />
331 * ```
332 */
333 itunes?: null | ItunesApp | undefined;
334 /**
335 * A brief description of what this web-page is about. Not recommended, superseded by description.
336 * It adds the `name="abstract"` meta tag.
337 *
338 * @see https://www.metatags.org/all-meta-tags-overview/meta-name-abstract/
339 * @example
340 * ```tsx
341 * "My Website Description"
342 * <meta name="abstract" content="My Website Description" />
343 * ```
344 */
345 abstract?: null | string | undefined;
346 /**
347 * The Facebook AppLinks metadata for the document.
348 * @example
349 * ```tsx
350 * { ios: { appStoreId: "123456789", url: "https://example.com" }, android: { packageName: "com.example", url: "https://example.com" } }
351 *
352 * <meta property="al:ios:app_store_id" content="123456789" />
353 * <meta property="al:ios:url" content="https://example.com" />
354 * <meta property="al:android:package" content="com.example" />
355 * <meta property="al:android:url" content="https://example.com" />
356 * ```
357 */
358 appLinks?: null | AppLinks | undefined;
359 /**
360 * The archives link rel property.
361 * @example
362 * ```tsx
363 * { archives: "https://example.com/archives" }
364 * <link rel="archives" href="https://example.com/archives" />
365 * ```
366 */
367 archives?: null | string | Array<string> | undefined;
368 /**
369 * The assets link rel property.
370 * @example
371 * ```tsx
372 * "https://example.com/assets"
373 * <link rel="assets" href="https://example.com/assets" />
374 * ```
375 */
376 assets?: null | string | Array<string> | undefined;
377 /**
378 * The bookmarks link rel property.
379 * @example
380 * ```tsx
381 * "https://example.com/bookmarks"
382 * <link rel="bookmarks" href="https://example.com/bookmarks" />
383 * ```
384 */
385 bookmarks?: null | string | Array<string> | undefined;
386 /**
387 * The category meta name property.
388 * @example
389 * ```tsx
390 * "My Category"
391 * <meta name="category" content="My Category" />
392 * ```
393 */
394 category?: null | string | undefined;
395 /**
396 * The classification meta name property.
397 * @example
398 * ```tsx
399 * "My Classification"
400 * <meta name="classification" content="My Classification" />
401 * ```
402 */
403 classification?: null | string | undefined;
404 /**
405 * Arbitrary name/value pairs for the document.
406 */
407 other?: ({
408 [name: string]: string | number | Array<string | number>;
409 } & DeprecatedMetadataFields) | undefined;
410}
411interface ResolvedMetadata extends DeprecatedMetadataFields {
412 metadataBase: null | URL;
413 title: null | AbsoluteTemplateString;
414 description: null | string;
415 applicationName: null | string;
416 authors: null | Array<Author>;
417 generator: null | string;
418 keywords: null | Array<string>;
419 referrer: null | ReferrerEnum;
420 /**
421 * @deprecated
422 */
423 themeColor: null | ThemeColorDescriptor[];
424 /**
425 * @deprecated
426 */
427 colorScheme: null | ColorSchemeEnum;
428 /**
429 * @deprecated
430 */
431 viewport: null | string;
432 creator: null | string;
433 publisher: null | string;
434 robots: null | ResolvedRobots;
435 alternates: null | ResolvedAlternateURLs;
436 icons: null | ResolvedIcons;
437 openGraph: null | ResolvedOpenGraph;
438 manifest: null | string | URL;
439 twitter: null | ResolvedTwitterMetadata;
440 facebook: null | ResolvedFacebook;
441 verification: null | ResolvedVerification;
442 appleWebApp: null | ResolvedAppleWebApp;
443 formatDetection: null | FormatDetection;
444 itunes: null | ItunesApp;
445 abstract: null | string;
446 appLinks: null | ResolvedAppLinks;
447 archives: null | Array<string>;
448 assets: null | Array<string>;
449 bookmarks: null | Array<string>;
450 category: null | string;
451 classification: null | string;
452 other: null | ({
453 [name: string]: string | number | Array<string | number>;
454 } & DeprecatedMetadataFields);
455}
456type RobotsFile = {
457 rules: {
458 userAgent?: string | string[] | undefined;
459 allow?: string | string[] | undefined;
460 disallow?: string | string[] | undefined;
461 crawlDelay?: number | undefined;
462 } | Array<{
463 userAgent: string | string[];
464 allow?: string | string[] | undefined;
465 disallow?: string | string[] | undefined;
466 crawlDelay?: number | undefined;
467 }>;
468 sitemap?: string | string[] | undefined;
469 host?: string | undefined;
470};
471type SitemapFile = Array<{
472 url: string;
473 lastModified?: string | Date | undefined;
474 changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never' | undefined;
475 priority?: number | undefined;
476 alternates?: {
477 languages?: Languages<string> | undefined;
478 } | undefined;
479 images?: string[] | undefined;
480 videos?: Videos[] | undefined;
481}>;
482type ResolvingMetadata = Promise<ResolvedMetadata>;
483declare namespace MetadataRoute {
484 type Robots = RobotsFile;
485 type Sitemap = SitemapFile;
486 type Manifest = ManifestFile;
487}
488interface Viewport extends ViewportLayout {
489 /**
490 * The theme color for the document.
491 * @example
492 *
493 * ```tsx
494 * "#000000"
495 * <meta name="theme-color" content="#000000" />
496 *
497 * { media: "(prefers-color-scheme: dark)", color: "#000000" }
498 * <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#000000" />
499 *
500 * [
501 * { media: "(prefers-color-scheme: dark)", color: "#000000" },
502 * { media: "(prefers-color-scheme: light)", color: "#ffffff" }
503 * ]
504 * <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#000000" />
505 * <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
506 * ```
507 */
508 themeColor?: null | string | ThemeColorDescriptor | ThemeColorDescriptor[] | undefined;
509 /**
510 * The color scheme for the document.
511 * @example
512 *
513 * ```tsx
514 * "dark"
515 * <meta name="color-scheme" content="dark" />
516 * ```
517 */
518 colorScheme?: null | ColorSchemeEnum | undefined;
519}
520type ResolvingViewport = Promise<Viewport>;
521interface ResolvedViewport extends ViewportLayout {
522 themeColor: null | ThemeColorDescriptor[];
523 colorScheme: null | ColorSchemeEnum;
524}
525export type { Metadata, ResolvedMetadata, ResolvingMetadata, MetadataRoute, Viewport, ResolvingViewport, ResolvedViewport, };