Skip to Content

SEO

Build metadata, structured data, and technical SEO endpoints with @puzzle-ui/seo.

@puzzle-ui/seo combines framework-independent graph and metadata utilities with React components and server route adapters. Use it to keep page metadata, Schema.org JSON-LD, sitemaps, and robots.txt consistent across an application.

Install

For a complete publication with dynamic pages and connected JSON-LD, follow Build a Searchable Publication. The tutorial's SEO utilities, React components, and framework endpoints have Stable APIs, with within-major backward-compatibility intent. See the maturity policy.

npm install @puzzle-ui/seo react

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

The React components documented in React Integration and the package's utility and adapter APIs have Stable classifications. API maturity does not guarantee production readiness; verify server-rendering, CSP, and framework behavior for your deployment.

Quick start

import { LDOrganization, SeoHead, SeoProvider } from "@puzzle-ui/seo";

export const App = () => (
  <SeoProvider
    config={{ siteUrl: "https://example.com", identity: { name: "Example" } }}
    metadata={{ title: "Home", canonical: "/" }}
  >
    <SeoHead />
    <LDOrganization name="Example" url="https://example.com" />
    <main>Welcome</main>
  </SeoProvider>
);

The provider collects schema nodes into one script; SeoHead renders the active metadata. Render the application on the server when metadata and structured data must be present in the initial response.

What the package provides

AreaDescriptionDocumentation
Metadata and URLsConfigure defaults, resolve page metadata and normalize URLs.Metadata and URLs
Structured dataBuild and validate Schema.org graphs and serialize JSON-LD.Structured Data
React integrationRender metadata and register schema nodes with a provider.React Integration
SitemapsGenerate sitemap files and indexes.Sitemaps
RobotsGenerate and validate robots.txt.Robots
ValidationInspect graph, schema, metadata and rich-result diagnostics.Validation
Server and frameworksServe endpoints with Fetch handlers and framework adapters.Framework Adapters
TestingAssert fixtures and inspect graph diagnostics.Testing

Entry points

ImportRuntime exports
@puzzle-ui/seoCore graph, React, validation, sitemap, robots, URL and testing exports; context, schema, metadata and server types.
@puzzle-ui/seo/coreGraph creation, merging, reference resolution, validation and serialization.
@puzzle-ui/seo/contextConfiguration and URL resolution helpers.
@puzzle-ui/seo/schemaSchema registry, generated definitions and node validation.
@puzzle-ui/seo/metadataMetadata and robots resolution.
@puzzle-ui/seo/reactProvider, metadata and Schema.org React components and hooks.
@puzzle-ui/seo/serverFramework-independent text and Fetch route handlers.
@puzzle-ui/seo/sitemapSitemap generation and XML helpers.
@puzzle-ui/seo/robotsrobots.txt validation and generation.
@puzzle-ui/seo/testingFixtures, assertions, inspection and diagnostic formatting.
@puzzle-ui/seo/validationComplete SEO validation.
@puzzle-ui/seo/urlsURL normalization and origin helpers.
@puzzle-ui/seo/next, /tanstack, /react-routerFramework-specific route adapters.

Configuration and metadata resolver functions are subpath exports, not root runtime exports. The root SeoMetadata and SchemaReference names also have corresponding type exports; see their specific subpaths when importing the data types.