Skip to Content

Metadata and URLs

Configure site defaults and resolve page metadata and SEO URLs.

@puzzle-ui/seo resolves page metadata independently of React, including canonical URLs, social cards, robots directives, and language alternates.

Install

For defaults, dynamic page metadata, canonical URLs and social images used together, follow the SEO publication tutorial.

npm install @puzzle-ui/seo react

React 19 is a peer dependency. Framework adapters do not require a framework package at runtime.

Quick start

import { normalizeSeoConfig } from "@puzzle-ui/seo/context";
import { resolveSeoMetadata, resolveSeoRobots } from "@puzzle-ui/seo/metadata";

const config = normalizeSeoConfig({
  siteUrl: "https://example.com",
  defaultLocale: "en",
  supportedLocales: ["en", "nl"],
  title: { default: "Example", template: "%s | Example" },
  identity: { name: "Example" },
});

const page = resolveSeoMetadata({
  title: "About",
  description: "About Example",
  canonical: "/about",
  openGraph: { images: [{ url: "/social.png", alt: "Example" }] },
  robots: { index: true, follow: true },
}, config);
const robots = resolveSeoRobots(page, config);

title.template must include %s. Page title, description and canonical override configured defaults; title and description can also fall back to identity. A canonical is not inferred automatically. Open Graph URL falls back to canonical and then the site URL. Open Graph title and description fall back to the resolved values; Twitter images fall back to Open Graph images. The default Open Graph type is website, and the default Twitter card is summary_large_image.

Configuration

NameTypeDefaultDescription
siteUrlstringrequiredAbsolute HTTP(S) site URL.
defaultLocalestringenDefault page locale.
supportedLocalesstring[]default localeSupported locales; regional variants of a supported base language are accepted.
trailingSlash"always" | "never" | "preserve""never"Same-origin URL path policy.
titleSeoTitleConfigseparator " | "Default title and optional %s template.
defaultsSeoDefaultMetadata{}Default title, description, canonical and robots string.
metadataSeoMetadata{}Site-level title, description, canonical and robots string.
identitySeoSiteIdentity—Name and optional URL, logo, description and social links.
debugboolean—Optional application debug flag.

Page metadata

NameTypeDefaultDescription
title, descriptionstringsite defaultsPage text.
canonicalstringconfigured canonical or noneExplicit canonical URL.
localestringdefault localeSupported locale, normalized for casing.
robotsSeoRobotsMetadataconfigured robots or noneIndex/follow and preview directives.
openGraphSeoOpenGraphMetadataresolved from page and siteSocial title, description, type, URL, locale, site name and image objects.
twitterSeoTwitterMetadataresolved from page and Open GraphCard, text, image URLs, image alt, site and creator.
alternatesSeoHreflangMetadata—{ alternates: [{ locale, url }] } language links.
keywords, authorstring[], string—Page keywords and author.
publishedTime, modifiedTimestring—Article timestamps.

URL helpers and safety

import { normalizeSeoUrl, isSameSeoOrigin } from "@puzzle-ui/seo/urls";

const url = normalizeSeoUrl("/guide/", {
  baseUrl: "https://example.com",
  trailingSlash: "never",
  allowExternal: false,
});
const sameOrigin = isSameSeoOrigin(url, "https://example.com");

normalizeSeoUrl accepts HTTP(S) only and rejects credentials unless explicitly allowed. Its fallback base is https://example.com; supply your real base for relative URLs. Set allowExternal: false to enforce the base origin (external URLs are otherwise allowed). Metadata URL resolution also rejects credentials. Validate untrusted input and select an appropriate same-origin policy for your application.

Exports

  • @puzzle-ui/seo/context: normalizeSeoConfig, normalizeSeoPath, resolveSeoUrl and configuration types.
  • @puzzle-ui/seo/metadata: resolveSeoMetadata, resolveSeoRobots and metadata types.
  • @puzzle-ui/seo/urls: normalizeSeoPath, normalizeSeoUrl, normalizeSeoOrigin, isSameSeoOrigin, isValidSeoUrl, resolveSeoUrls and URL option/result types.