other metadata field for custom tags
The other field allows rendering any custom metadata tags not covered by built-in support. Values can be strings or arrays of strings for generating multiple meta tags with the same name.
Next.js · API reference · all subjects
functions
556 notes in this subject, read out of this brain and free to use. This is page 4 of 10.
JSDoc metadata typing for JavaScript projects
For JavaScript projects, use JSDoc annotation: /** @type {import("next").Metadata} */ export const metadata = { ... }
typescript inferred metadata typing
When using the built-in TypeScript plugin in your IDE, type inference for Metadata is automatic. You can explicitly add 'import type { Metadata } from 'next'' and use it as type annotation.
PageProps and LayoutProps type helpers
For type completion of params and searchParams in generateMetadata, use PageProps<'/route'> for pages and LayoutProps<'/route'> for layouts as type helpers.
generateMetadata example with dynamic routes
export async function generateMetadata({ params, searchParams }, parent) { const { id } = await params; const product = await fetch(`https://.../${id}`).then(res => res.json()); const previousImages = (await parent).openGraph?.images || []; return { title: product.title, openGraph: { images: ['/some-specific-page-image.jpg', ...previousImages] } } }
htmlLimitedBots configuration
The htmlLimitedBots option in next.config.js can override the default User Agent list for HTML-limited bots that cannot execute JavaScript. Streaming metadata is disabled for these bots. Set htmlLimitedBots: /.*/ to fully disable streaming metadata.
Resource hints using ReactDOM methods
Resource hints like preload, preconnect, and prefetchDNS can be added using ReactDOM methods: ReactDOM.preload(href, {as}), ReactDOM.preconnect(href, {crossOrigin}), ReactDOM.prefetchDNS(href). These methods are only supported in Client Components but are server-side rendered on initial load. Next.js in-built features like next/font, next/image, and next/script automatically handle relevant resource hints.
Metadata evaluation order
Metadata is evaluated in order from the root segment down to the segment closest to the final page.js segment. For a route like app/blog/[slug]/page.tsx, evaluation order is: app/layout.tsx → app/blog/layout.tsx → app/blog/[slug]/page.tsx.
facebook metadata configuration
facebook object can contain either appId or admins (not both). admins can be a string or array of strings for multiple admin IDs.
verification metadata
verification object can contain: google (string), yandex (string), yahoo (string), other (object with custom verification keys that can be strings or arrays).
alternates metadata for localization
alternates object contains: canonical (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).
appleWebApp metadata structure
appleWebApp object contains: title (string), statusBarStyle (string like 'black-translucent'), startupImage (string or array of strings/objects with url and media properties). itunes object contains appId and appArgument.
title.absolute ignores parent template
title.absolute provides a title that ignores title.template set in parent segments. This allows child segments to opt out of parent title templating.
twitter metadata for cards
twitter object contains: card (string like 'summary_large_image' or 'app'), title, description, siteId, creator, creatorId, images (must be absolute URLs). For app card type, includes app object with name and id/url for iphone, ipad, googleplay.
icons metadata configuration
icons object can contain: icon (string or array), shortcut (string or array), apple (string or array), other (object or array with rel and url). Each icon can have url, media, sizes, type properties. File-based Metadata API is recommended as an alternative.
robots metadata fields
robots object contains: index (boolean), follow (boolean), nocache (boolean), googleBot object with index, follow, noimageindex, max-video-preview, max-image-preview, max-snippet properties.
openGraph metadata structure
openGraph object can contain: title, description, url, siteName, type, locale, images (array of objects with url, width, height, alt), videos (array with url, width, height), audio (array with url). For article type: publishedTime, authors. Images and videos URLs must be absolute.
URL composition with metadataBase examples
Given metadataBase 'https://acme.com': '/' resolves to 'https://acme.com', './' resolves to 'https://acme.com', 'payments' resolves to 'https://acme.com/payments', '/payments' resolves to 'https://acme.com/payments', './payments' resolves to 'https://acme.com/payments', '../payments' resolves to 'https://acme.com/payments', 'https://beta.acme.com/payments' resolves to 'https://beta.acme.com/payments'.
metadataBase composition rules
metadataBase is a convenience option to set a base URL prefix for metadata fields that require a fully qualified URL. Trailing slashes between metadataBase and metadata fields are normalized. An absolute path in a metadata field is treated as a relative path starting from the end of metadataBase. If a metadata field provides an absolute URL, metadataBase is ignored. Using a relative path without configuring metadataBase causes a build error.
title field with template
title.template can add a prefix or suffix to titles defined in child route segments using %s as a placeholder. title.default is required when creating a template. title.template applies only to child segments, not the segment where it's defined. title.template in layout.js will not apply to title in page.js of the same route segment.
Unsupported metadata that require alternative approaches
Unsupported metadata includes: <meta http-equiv> (use redirect(), Proxy, or Security Headers), <base> (render in layout/page), <noscript> (render in layout/page), <style> (use CSS), <script> (use next/script), <link rel="stylesheet"> (import directly), <link rel="preload"> (use ReactDOM.preload), <link rel="preconnect"> (use ReactDOM.preconnect), <link rel="dns-prefetch"> (use ReactDOM.prefetchDNS).
appLinks metadata for deep linking
appLinks object contains: ios (object with url and app_store_id), android (object with package and app_name), web (object with url and should_fallback boolean).
Metadata fields supported
Supported metadata fields include: title (string or object with default/template/absolute), description, generator, applicationName, referrer, keywords, authors, creator, publisher, formatDetection, metadataBase, openGraph, robots, icons, manifest, twitter, verification, appleWebApp, alternates, appLinks, archives, assets, bookmarks, category, facebook, pinterest, other, and itunes.
generateMetadata fetch memoization
fetch requests inside generateMetadata are automatically memoized for the same data across generateMetadata, generateStaticParams, Layouts, Pages, and Server Components. React cache() can be used if fetch is unavailable.
Streaming metadata with generateMetadata
If generateMetadata doesn't introduce dynamic behavior and the page can be prerendered, resulting metadata is included in the page's initial HTML. Otherwise, metadata resolved from generateMetadata can be streamed after sending the initial UI. Next.js automatically detects HTML-limited bots (like facebookexternalhit) that cannot execute JavaScript and will block page rendering until metadata is resolved for these bots.
generateMetadata with Cache Components behavior
When Cache Components is enabled, generateMetadata follows the same rules as other components. If metadata accesses runtime data (cookies(), headers(), params, searchParams) or performs uncached data fetching, it defers to request time. If other parts of the page also defer to request time, prerendering generates a static shell with metadata streamed in. If the page is otherwise fully prerenderable, an error is raised requiring explicit choice to cache data or signal intentional deferred rendering.
Metadata merging behavior
Metadata objects from multiple segments are shallowly merged together. Duplicate keys are replaced based on evaluation order. Nested fields like openGraph and robots from earlier segments are completely overwritten by later segments, not merged. To share nested fields between segments, pull them into a separate variable and spread them.
generateMetadata parent parameter
The parent parameter in generateMetadata is a Promise<ResolvingMetadata> that allows access to the resolved metadata from parent route segments. This enables extending rather than replacing parent metadata, commonly used with openGraph images.
generateMetadata parameters: params and searchParams types
In generateMetadata, params is a Promise<{ [key: string]: string | string[] }> containing dynamic route parameters from root segment down to the current segment. searchParams is a Promise<{ [key: string]: string | string[] | undefined }> containing the URL search parameters. Both are only available in page.js, not layout.js for searchParams.
generateMetadata is Server Component only
generateMetadata and the metadata export are only supported in Server Components because metadata must be resolved on the server before the page component is rendered. This allows Next.js to include the metadata in the initial HTML response. If you need Client Component features, keep your page as a Server Component and move Client Component logic to a separate file with 'use client' directive.
metadata object vs generateMetadata function
The metadata object is used for static metadata exported from layout.js or page.js. generateMetadata is used for dynamic metadata. You cannot export both the metadata object and generateMetadata function from the same route segment.
generateMetadata function definition
generateMetadata is an async function that returns a Metadata object. It accepts props containing params and searchParams (both Promises), and a parent parameter that is a Promise of ResolvingMetadata. The function is used for dynamic metadata that depends on route parameters, external data, or parent segment metadata. It must be exported from layout.js or page.js files.
File-based metadata priority
File-based metadata has higher priority and will override the metadata object and generateMetadata function.
next/root-params in shared utility code
Root parameter getters are module imports and can be called from any Server Component or server-side utility, not just layouts and pages. You do not need to add 'import "server-only"' to files that use next/root-params as the import already fails at build time if used in a Client Component.
Why root parameters are special
The root layout is the top-level rendering boundary. The route parameters before it are shared by all routes under that root layout, which makes them safe to access from any Server Component in that tree. Route parameters deeper in the route vary depending on which child page is being rendered, so they are only available through the params prop in the page or layout that defines them.
Root parameters not available in Server Actions
Root parameter getters cannot be used in Server Actions. Attempting to call them will result in an error.
Root parameters not available in unstable_cache
Calling a root parameter getter inside unstable_cache will throw a runtime error. Use 'use cache' instead.
Root parameters with catch-all segments
Root parameters work with catch-all and optional catch-all segments. A catch-all segment like [...path] returns string[], while an optional catch-all like [[...path]] returns string[] | undefined.
Multiple root layouts and parameter typing
When an application has multiple root layouts with different parameters, getter functions are typed to account for usage in any of all possible routes. A parameter that does not exist in every root layout has the type string | undefined.
Root parameters with caching directives
Because root parameter getters are imported functions, Next.js can track which ones a cached function uses. Only those root parameters become part of the cache key, so cache entries are not split across unrelated parameter values.
generateStaticParams with root parameters
Root parameters are available as soon as routes that define them are created. A generateStaticParams function is only required with Cache Components, where each root parameter must have at least one value or the build fails.
Root parameter types generation
Types for next/root-params exports are generated during next dev, next build, or next typegen, the same as PageProps and LayoutProps.
next/root-params usage restrictions
next/root-params can be used in Server Components only. It cannot be used in Client Components, Server Actions, or Route Handlers. Support for Route Handlers is planned for a future release. Using next/root-params in a Client Component will cause a build error.
Root parameter naming requirements
Root parameter names must be valid JavaScript function identifiers. Kebab-cased segment names (e.g. [post-slug]) are not supported and will cause an error at dev time or during build.
Root parameters vs regular params prop
Root parameters are dynamic segments that appear before the root layout. Unlike the regular params prop, root parameter getters can be called from any Server Component in the application without prop drilling. This makes them useful for values like language or locale segments that need to be accessed across the application.
Root parameter return types
Each root parameter getter returns a Promise. Dynamic segments like [id] return string. Catch-all segments like [...path] return string[]. Optional catch-all segments like [[...path]] return string[] | undefined. If a parameter does not exist in the current route's root layout, the return type includes undefined.
next/root-params module overview
The next/root-params module provides getter functions for accessing root-level parameters in Server Components. Each root parameter is exported as an async function that resolves to the parameter value for the current route. Export names are generated from dynamic segment folder names—for example, if the root layout is inside app/[locale], you import locale from next/root-params.
next/root-params version history
next/root-params was introduced in v16.3.0.
Root parameter route structure example
Example file structure showing root parameters: app/[lang]/layout.tsx (root layout with lang parameter), app/[lang]/page.tsx (has no slug), app/[lang]/blog/[slug]/page.tsx (slug is a route parameter, not root), app/[lang]/store/[...slug]/page.tsx (catch-all route parameter). Only lang is a root parameter; slug variations are regular route parameters accessed through the params prop.
Reading root parameters in nested generateStaticParams
Inside a nested segment's generateStaticParams, you can read a root parameter directly with its getter function instead of destructuring it from the params argument.
next/root-params example with lang parameter
Example usage in a root layout: import { lang } from 'next/root-params'; export default async function RootLayout(props: LayoutProps<'/[lang]'>) { return <html lang={await lang()}><body>{props.children}</body></html>; }
refresh usage error in Route Handler
If you attempt to call refresh from a Route Handler, it will throw an error. Example of incorrect usage: ```ts import { refresh } from 'next/cache' export async function POST() { // This will throw an error refresh() } ```
refresh example with createPost Server Action
Example showing refresh usage in a Server Action: ```ts 'use server' import { refresh } from 'next/cache' export async function createPost(formData: FormData) { const title = formData.get('title') const content = formData.get('content') // Create the post in your database const post = await db.post.create({ data: { title, content }, }) refresh() } ``` This example demonstrates calling refresh after creating a post in the database to refresh the client router.
refresh can only be called from Server Actions
refresh can only be called from within Server Actions. It cannot be used in Route Handlers, Client Components, or any other context. Attempting to use it outside Server Actions will throw an error.
refresh function parameters and return type
The refresh function signature is refresh(): void. It takes no parameters and does not return a value.
refresh function overview
The refresh function allows you to refresh the client router from within a Server Action. It is imported from 'next/cache'.
permanentRedirect default behavior for type parameter
By default, permanentRedirect uses 'push' (adding a new entry to the browser history stack) in Server Actions and 'replace' (replacing the current URL in the browser history stack) everywhere else.
permanentRedirect parameters
permanentRedirect accepts the following parameters: path (type: string, required) - the URL to redirect to, can be relative or absolute; type (type: 'replace' (default) or 'push' (default in Server Actions), optional) - the type of redirect to perform.
permanentRedirect function signature
The permanentRedirect function accepts two arguments: path (string) and type (optional 'replace' or 'push'). It does not return a value.
permanentRedirect usage contexts
permanentRedirect can be used in Server Components, Client Components, Route Handlers, and Server Functions (also called Server Actions).