metadata

Describe the document head of a page or layout - title, description, Open Graph, canonical URL and more - as a static object.

import type { Metadata } from '@gio.js/core';

export const metadata: Metadata = {
  metadataBase: 'https://acme.example',
  title: { default: 'Acme', template: '%s | Acme' },
  description: 'The Acme store.',
  openGraph: { siteName: 'Acme', images: '/og.png' },
};

import type { Metadata } from '@gio.js/core';

export const metadata: Metadata = {
  title: 'Pricing',                                  // <title>Pricing | Acme</title>
  alternates: { canonical: '/pricing' },             // https://acme.example/pricing
};

metadata is read from layout.tsx, page.tsx, not-found.tsx and error.tsx. For values that depend on the request or on data, export generateMetadata instead (or as well).

Reference

Fields

Every field is optional. null removes a value a layout above set.

How segments merge

• The root layout comes first, then each nested layout down to the page. The merge is shallow: the deepest segment that sets a top-level field wins it whole. A page that sets openGraph replaces the layout's entire openGraph object - share common values through a variable.
• undefined (a field left out) inherits; null removes the inherited value.
• A layout's title.template never applies to the layout's own title, only to titles set below it.
• In one module, what generateMetadata returns is merged over the static metadata field by field.

Behavior

• The tags render into the <head> on the server, streamed pages included, and are replaced on every client-side navigation. Every value is rendered by React, so it is HTML-escaped.
• A metadata title supersedes a <title> a component renders: the server HTML keeps only the metadata one, and development mode warns.
• A URL that should be absolute but stays relative (no metadataBase and no GIO_SITE_URL) logs a warning once per route. The request's Host header is never used as a base: on a cached page a client-chosen host would reach every visitor.
• icons and manifest URLs are not resolved against metadataBase: the browser resolves them against the page.
• The static metadata export is plain data: a value that is not an object is ignored.

Examples

Keep a page out of search results

import type { Metadata } from '@gio.js/core';

export const metadata: Metadata = {
  title: 'Your account',
  robots: { index: false, follow: true },   // <meta name="robots" content="noindex, follow">
};

export default function Account() {
  return <h1>Your account</h1>;
}

Alternate languages

import type { Metadata } from '@gio.js/core';

export const metadata: Metadata = {
  title: 'Pricing',
  alternates: {
    canonical: '/pricing',
    languages: { de: '/de/pricing', 'x-default': '/pricing' },
  },
};

export default function Pricing() {
  return <h1>Pricing</h1>;
}

A not-found page that is not indexed

import type { Metadata } from '@gio.js/core';

export const metadata: Metadata = { title: 'Not found', robots: 'noindex' };

export default function NotFound() {
  return <h1>This page does not exist</h1>;
}

Good to know

• Hand-written head tags in the root layout other than <title> (charset, viewport, a description) are not deduplicated: declare each tag in one place.
• There is no viewport export, no file-based icons (app/icon.png) and no generated Open Graph images (opengraph-image.tsx). Put icons in public/ and reference them from icons.
• For JSON-LD structured data, render <JsonLd> in the page.

Related

• Metadata & SEO - the guide
• generateMetadata
• sitemap.ts, robots.ts, manifest.ts
• layout.tsx, not-found.tsx

Version history