metadata object - static metadata export
To define static metadata, export a `Metadata` object from a `layout.js` or `page.js` file. The `Metadata` type is imported from 'next'. Static metadata does not depend on dynamic information.
Next.js · API reference · all subjects
file-conventions & metadata
37 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
metadata in layouts and pages
Metadata can be added to `layout.js` and `page.js` files. Next.js will automatically resolve the metadata and create the relevant `<head>` tags for the page.
File-based metadata priority
File-based metadata has higher priority and will override the `metadata` object and `generateMetadata` function.
title metadata field - string
The `title` field in metadata can be a simple string that sets the document title, which renders as `<title>` tag in the HTML head.
title.default metadata field
`title.default` provides a fallback title to child route segments that don't define their own `title`. It is used as a base title when no explicit title is provided in nested routes.
title.template metadata field
`title.template` can be used to add a prefix or suffix to titles defined in child route segments. It uses the pattern `%s` as a placeholder for the child segment's title. A `title.default` is required when creating a template. The template applies to child route segments and not the segment it's defined in. Templates defined in `layout.js` will not apply to a title in a `page.js` of the same route segment. Templates defined in `page.js` have no effect because pages are always terminating segments.
title.absolute metadata field
`title.absolute` provides a title that ignores `title.template` set in parent segments. It allows overriding inherited title templates from parent routes.
description metadata field
The `description` metadata field sets the page description, which renders as `<meta name="description" content="..." />` in the HTML head.
metadata fields - generator, applicationName, referrer, keywords, authors, creator, publisher
Metadata fields: `generator` (string), `applicationName` (string), `referrer` (string), `keywords` (array of strings), `authors` (array of objects with optional `name` and `url`), `creator` (string), `publisher` (string). These render as appropriate meta tags in the HTML head.
metadata formatDetection field
The `formatDetection` field controls automatic format detection with properties: `email` (boolean), `address` (boolean), `telephone` (boolean). Set to false to disable detection of these formats. Renders as `<meta name="format-detection" content="..." />`.
metadataBase - base URL for metadata fields
`metadataBase` is a convenience option to set a base URL prefix for metadata fields that require fully qualified URLs. It allows URL-based metadata fields defined in the current route segment and below to use relative paths instead of absolute URLs. The relative path is composed with `metadataBase` to form a fully qualified URL. If a metadata field provides an absolute URL, `metadataBase` will be ignored. Using a relative path in a URL-based metadata field without configuring `metadataBase` will cause a build error.
metadataBase typical usage
`metadataBase` is typically set in the root `app/layout.js` to apply to URL-based metadata fields across all routes. It can contain a subdomain (e.g. `https://app.acme.com`) or base path (e.g. `https://acme.com/start/from/here`).
URL composition with metadataBase
URL composition between `metadataBase` and metadata fields: trailing slashes are normalized; an 'absolute' path in a metadata field (starting with /) is treated as a 'relative' path from the end of `metadataBase`. Examples: `/` resolves to metadataBase root, `./` resolves to metadataBase root, `payments` becomes `metadataBase/payments`, `/payments` becomes `metadataBase/payments`, `./payments` becomes `metadataBase/payments`, `../payments` becomes `metadataBase/payments`, absolute URLs are preserved.
openGraph metadata field
The `openGraph` metadata field defines Open Graph tags. It supports: `title` (string), `description` (string), `url` (string), `siteName` (string), `images` (array of objects with `url`, `width`, `height`, `alt`), `videos` (array of objects with `url`, `width`, `height`), `audio` (array of objects with `url`), `locale` (string), `type` (string such as 'website' or 'article'). For article type: `publishedTime` (ISO string), `authors` (array of strings). Images and videos must have absolute URLs.
robots metadata field
The `robots` metadata field controls search engine crawling. Properties: `index` (boolean), `follow` (boolean), `nocache` (boolean). Also supports `googleBot` object with: `index` (boolean), `follow` (boolean), `noimageindex` (boolean), `max-video-preview` (number, -1 for unlimited), `max-image-preview` (string like 'large'), `max-snippet` (number, -1 for unlimited).
icons metadata field
The `icons` metadata field defines favicon and app icons. Can be a string or object with: `icon` (string or array of objects/URLs with optional `media` property), `shortcut` (string or array), `apple` (string or array of objects with optional `sizes` and `type` properties), `other` (object with `rel` and `url`, or array). Can use relative or absolute URLs.
icons metadata - file-based API recommended
It is recommended to use the file-based Metadata API for icons where possible rather than the config export, as the file-based API will automatically generate the correct metadata.
manifest metadata field
The `manifest` metadata field specifies a web application manifest URL as defined in the Web Application Manifest specification. It renders as `<link rel="manifest" href="..." />`.
twitter metadata field
The `twitter` metadata field defines Twitter Card tags. For summary_large_image card: `card` ('summary_large_image'), `title` (string), `description` (string), `siteId` (string), `creator` (string), `creatorId` (string), `images` (array of absolute URLs). For app card: `card` ('app'), plus `app` object with `name` (string), `id` (object with `iphone`, `ipad`, `googleplay`), `url` (object with `iphone`, `ipad`). Images must be absolute URLs.
verification metadata field
The `verification` metadata field enables site verification with properties: `google` (string), `yandex` (string), `yahoo` (string), `other` (object with custom verification names as keys and values as strings or arrays). Renders as appropriate meta tags.
appleWebApp and itunes metadata fields
The `appleWebApp` metadata field configures web app capabilities: `title` (string), `statusBarStyle` (string like 'black-translucent'), `startupImage` (string or array of strings/objects with optional `media` property). The `itunes` metadata field has: `appId` (string), `appArgument` (string).
alternates metadata field
The `alternates` metadata field defines alternate versions of a page: `canonical` (string URL), `languages` (object with language codes as keys and URLs as values), `media` (object with media queries as keys and URLs as values), `types` (object with MIME types as keys and URLs as values).
appLinks metadata field
The `appLinks` metadata field defines app links: `ios` (object with `url`, `app_store_id`), `android` (object with `package`, `app_name`), `web` (object with `url`, `should_fallback` boolean).
archives, assets, bookmarks metadata fields
The `archives` metadata field describes a collection of historical records/documents (array of URLs). The `assets` metadata field specifies assets location (array of URLs). The `bookmarks` metadata field lists bookmarks (array of URLs). Each renders as appropriate `<link rel="..." />` tags.
pagination metadata field
The `pagination` metadata field describes pagination in a sequence: `previous` (string URL), `next` (string URL). Renders as `<link rel="prev" />` and `<link rel="next" />` tags.
category and facebook metadata fields
The `category` metadata field is a string that renders as `<meta name="category" />`. The `facebook` metadata field has either `appId` (string) or `admins` (string or array), but not both. `admins` can be an array to generate multiple `fb:admins` meta tags.
pinterest metadata field
The `pinterest` metadata field controls Pinterest Rich Pins: `richPin` (boolean). Renders as `<meta name="pinterest-rich-pin" />`.
other metadata field - custom metadata tags
The `other` metadata field allows rendering custom metadata tags not covered by built-in support. It accepts an object with tag names as keys and string or array of strings as values. Arrays generate multiple meta tags with the same name.
Metadata type for type safety
Import the `Metadata` type from 'next' to add type safety to metadata exports. For `generateMetadata` async functions, return type is `Promise<Metadata>`. The built-in TypeScript plugin automatically provides type completion without manual addition.
Unsupported metadata types
The following metadata types do not have built-in support but can be rendered in layout or page: `<meta http-equiv="...">` (use HTTP Headers via redirect(), Proxy, or Security Headers), `<base>`, `<noscript>`, `<style>`, `<script>`, `<link rel="stylesheet" />`, `<link rel="preload" />`, `<link rel="preconnect" />`, `<link rel="dns-prefetch" />`.
Default meta tags always added
Two default meta tags are always added even if metadata is not defined: the meta charset tag that sets character encoding to utf-8, and the meta viewport tag with `content="width=device-width, initial-scale=1"`.
Metadata ordering and evaluation
Metadata is evaluated in order from root segment down to the segment closest to the final `page.js` segment. For example: 1) `app/layout.tsx`, 2) `app/blog/layout.tsx`, 3) `app/blog/[slug]/page.tsx`.
Metadata merging - shallow merge with replacement
Metadata objects from multiple segments in the same route are shallowly merged. Duplicate keys are replaced based on ordering. Nested fields like `openGraph` and `robots` defined in earlier segments are overwritten by later segments. Fields not redefined in child segments are inherited from parent segments.
Metadata overwriting fields example
When a child route segment defines metadata with nested fields (e.g., `openGraph`), it completely replaces the parent's nested field object. To share some nested fields while overwriting others, pull shared fields into a separate variable and spread them using the spread operator.
searchParams availability in generateMetadata
`searchParams` are only available in `page.js` segments, not in `layout.js` segments.
Static metadata preference over generateMetadata
If metadata doesn't depend on request information, it should be defined using the static `metadata` object rather than `generateMetadata` for better performance.
Version history - generateMetadata
v15.2.0: Introduced streaming support to `generateMetadata`. v14.0.0: `viewport`, `themeColor`, and `colorScheme` deprecated in favor of `viewport` configuration (generate-viewport). v13.2.0: `metadata` and `generateMetadata` introduced.