> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it.
> Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`.
> Before using any code sample, read `@weaverse/hydrogen` in the project's `package.json`: 6.x and 5.x import from different entries and use different type names, so code for one does not build on the other.
> `@weaverse/hydrogen` 6 (Shopify Hydrogen 2026.10 and later, the version these docs show) imports from `@weaverse/hydrogen/react-router` and uses `Weaverse*` types such as `WeaverseComponentProps`, `WeaverseComponentLoaderArgs` and `WeaverseComponentSchema`; the root `@weaverse/hydrogen` entry only exports `createSchema()`, data helpers and types.
> `@weaverse/hydrogen` 5.x (Hydrogen 2026.4 and earlier) imports everything from `@weaverse/hydrogen` and uses `HydrogenComponentProps`, `ComponentLoaderArgs` and `HydrogenComponentSchema`. On a 5.x project, convert samples to these names. Upgrade to 6 only when asked (`npx @weaverse/cli@latest migrate v6`, plus the Hydrogen 2026.10 upgrade). Do not mix major versions.
> Next.js themes use `@weaverse/hydrogen` 6.2.0 or later: import client and shared code from `@weaverse/hydrogen/next` and server-only code from `@weaverse/hydrogen/next/server`. `@weaverse/next` is deprecated; never install or import it.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://weaverse.io/docs/developer-tools/weaverse-mcp

# Page SEO

> Wire Weaverse Studio's per-page SEO editor into your Hydrogen storefront.

# Page SEO

Weaverse Studio lets merchants edit per-page SEO metadata (title, description, canonical, robots, Open Graph, Twitter card, JSON-LD) on every Weaverse page. To render those tags on the storefront, your theme needs to forward `weaverseData` to a single helper — `getWeaverseSeoMeta` — from a `meta` export.

This guide explains where to wire the helper, how it interacts with code-defined SEO, and how to clean up any legacy override layer. It is written so you can apply it to any Hydrogen theme without prior knowledge of the file layout.

> **What changes on the storefront?** The routes you opt in export `meta` that returns the SEO tags configured in Studio. Precedence is per route, not global: routes whose SEO is already derived from Shopify data (products, collections, Shopify pages) keep their code-defined SEO, and — in Pilot — so does the real homepage (`INDEX`). Pages without SEO configured in Studio fall through silently (no overrides).

***

## Prerequisites

* Hydrogen 2026.10 with `@weaverse/hydrogen` **6** (the samples import from `@weaverse/hydrogen/react-router`).
* A Hydrogen route that loads a Weaverse page via `context.weaverse.loadPage(...)`.

If your theme is on an older SDK, install v6:

```bash theme={null}
npm install @weaverse/hydrogen@^6
```

`getWeaverseSeoMeta` was introduced in `@weaverse/hydrogen` 5.14.0. A theme still on classic Hydrogen (2026.4 or earlier) can use it from `@weaverse/hydrogen@^5.14.0`, importing from `@weaverse/hydrogen` instead of `@weaverse/hydrogen/react-router`; moving to v6 means moving to Hydrogen 2026.10, as described in the [v6 migration guide](https://weaverse.io/docs/migration-advanced/v6-migration.md).

***

## TL;DR

In a route that should take its SEO from Studio (a `CUSTOM` page route, for example), export `meta` like this:

```tsx theme={null}
import { getWeaverseSeoMeta } from "@weaverse/hydrogen/react-router";
import type { MetaFunction } from "react-router";

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  return getWeaverseSeoMeta(data?.weaverseData);
};
```

`getWeaverseSeoMeta` reads the SEO record embedded in the loaded page and returns the meta-tag array that React Router's `meta` export expects. If the page has no SEO configured, it returns a minimal `robots: index,follow` descriptor — safe to call unconditionally.

The rest of this guide covers three real-world patterns and the cleanup steps you typically need.

***

## Where to wire it

You decide per route whether Studio-edited SEO should apply. The routes that benefit most are the ones rendering Weaverse `CUSTOM` pages: the catch-all that serves [custom pages](https://weaverse.io/docs/features/custom-pages.md), and the home/index route when it also serves root-level custom handles. Template routes (product, collection, Shopify page) are an optional supplement — they normally keep their Shopify-derived SEO.

The recipes below are independent of each other; the route file determines which one applies.

### Catch-all route — CUSTOM pages

Most themes have a catch-all route that resolves any unmatched URL into a Weaverse CUSTOM page. Typical filenames: `routes/catch-all.tsx`, `routes/($locale).$.tsx`, `routes/$.tsx`. If your catch-all currently has no `meta` export, add one.

**Before**

```tsx theme={null}
export async function loader({ context }: LoaderFunctionArgs) {
  const weaverseData = await context.weaverse.loadPage({ type: "CUSTOM" });
  // …validation…
  return { weaverseData };
}

export default function Component() {
  return <WeaverseContent />;
}
```

**After**

```tsx theme={null}
import { getWeaverseSeoMeta } from "@weaverse/hydrogen/react-router";
import type { MetaFunction } from "react-router";

export async function loader({ context }: LoaderFunctionArgs) {
  const weaverseData = await context.weaverse.loadPage({ type: "CUSTOM" });
  // …validation…
  return { weaverseData };
}

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  return getWeaverseSeoMeta(data?.weaverseData);
};

export default function Component() {
  return <WeaverseContent />;
}
```

### Home / index route — INDEX (and root-level CUSTOM)

Many themes serve both the real homepage (`type: "INDEX"`) **and** root-level CUSTOM handles from the same index route. Pilot's `app/routes/home.tsx` splits the two: the real homepage keeps its code-defined SEO (`seoPayload.home({ shop })`, which reflects the shop name), while root-level CUSTOM handles served by the same route get their SEO from Weaverse.

**Loader** — compute `seo` only for INDEX, leave it `null` for CUSTOM, and return both `weaverseData` and `seo`:

```tsx theme={null}
import type { PageType } from "@weaverse/hydrogen/react-router";
import { CACHE_LONG } from "~/utils/cache";
import { unwrapStorefront } from "~/utils/storefront";

export async function loader(args: LoaderFunctionArgs) {
  const { params, context } = args;
  // NOTE: This locale-detection pattern assumes the index route sits under a
  // `:locale?` prefix, so params.locale holds the first URL segment.
  // Adjust to match your theme's own locale-detection logic.
  const { pathPrefix } = context.storefront.i18n;
  const locale = pathPrefix?.slice(1) || "";
  let type: PageType = "INDEX";

  // If the first segment is not a supported locale, treat it as a custom handle.
  if (params.locale && params.locale.toLowerCase() !== locale) {
    type = "CUSTOM";
  }

  const [weaverseData, { shop }] = await Promise.all([
    context.weaverse.loadPage({ type }),
    context.storefront
      .graphql(SHOP_QUERY, { cache: CACHE_LONG })
      .then(unwrapStorefront),
  ]);

  // INDEX uses the code-defined homepage SEO; CUSTOM pages (root-level
  // Weaverse handles served by this route) get their SEO from Weaverse
  // via getWeaverseSeoMeta in the meta export below.
  const seo = type === "INDEX" ? seoPayload.home({ shop }) : null;

  return { shop, weaverseData, seo };
}
```

**Meta** — code-defined SEO when it exists (INDEX), Weaverse SEO otherwise (CUSTOM):

```tsx theme={null}
import { getWeaverseSeoMeta } from "@weaverse/hydrogen/react-router";
// Hydrogen 2026.10 removed `getSeoMeta`; Pilot ships a port with the same output
import { getSeoMeta, type SeoConfig } from "~/utils/seo-meta";

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  // INDEX (the real homepage) keeps the code-defined SEO — no Weaverse
  // override. CUSTOM pages served by this route have `seo: null`, so they fall
  // through to Weaverse.
  if (data?.seo) {
    return getSeoMeta(data.seo as SeoConfig);
  }
  return getWeaverseSeoMeta(data?.weaverseData);
};
```

> **Want merchants to edit homepage SEO from Studio too?** That is a deliberate theme decision, not the default. Invert the branch — prefer `getWeaverseSeoMeta(data?.weaverseData)` when the merchant has filled in a title or description in Studio, and fall back to `seoPayload.home({ shop })` otherwise — so the homepage never ships with empty meta tags. Note the tradeoff: whichever way you choose, tell your merchants, because a field they edit in Studio for a route that keeps code-defined SEO will silently have no effect on the storefront.

### Template routes — optional supplement (product, collection, blog, page)

Routes for Shopify resources (product, collection, blog, article, Shopify pages) typically build their SEO from the Shopify payload via `seoPayload.product(...)`, `seoPayload.collection(...)`, etc. **Leave those as-is.** For templates, Shopify-driven SEO already covers the resource-specific fields (including structured JSON-LD with price, availability, ratings, etc.) that Weaverse Studio does not surface today.

> **If you want Weaverse SEO to supplement template routes**: Add `getWeaverseSeoMeta` to the template's `meta` export and **append** it after the Shopify tags, not replace them. Avoid concatenating arrays naively — duplicate `<meta name="description">` tags can confuse crawlers. The safest pattern is to let Shopify SEO win and only pull in Weaverse tags that are absent from the Shopify payload (e.g. a custom `robots` override or extra OG fields).

***

## Step-by-step: applying this to a theme

1. **Bump the SDK** to `@weaverse/hydrogen@^6` (Hydrogen 2026.10) and reinstall. On classic Hydrogen, use `@weaverse/hydrogen@^5.14.0` instead.
2. **Locate every route that calls `context.weaverse.loadPage(...)`** — `grep -rln "weaverse.loadPage" app/routes`.
3. **For each, decide which recipe applies** (catch-all, home/index, or — optionally — template) and apply it. Routes that already build SEO from Shopify data stay as they are.
4. **Remove legacy overrides** (see next section), if any.
5. **Run `typecheck` and `build`.** Fix any `errorComponent` regression caused by the SDK bump (see [SDK 5.14 side effect](#sdk-5-14-error-component-prop-type)).
6. **Smoke test**: open a Weaverse page in Studio, set a Title and Description, save, view source on the storefront URL. The tags should appear.

***

## Removing a legacy override layer

Some themes shipped a hardcoded SEO override config to brand custom pages before Studio could edit SEO. Typical signatures:

* A file like `app/.server/seo-overrides.ts`, `app/utils/seo-overrides.ts`, or similar, with a hardcoded `Record<string, { title, description }>`.
* A helper like `seoPayload.customPage({ url })` that maps the URL to one of those overrides.
* A route that does `seoPayload.customPage({ url: request.url })` and returns it in the loader.

Once Studio-edited SEO works, this layer is dead weight and competes with Weaverse:

1. Delete the override file (e.g. `seo-overrides.ts`).
2. Remove `customPage` from your SEO payload module — both the function and its export.
3. Update routes that called `seoPayload.customPage({ url: request.url })` — replace with the `meta` export pattern above. The loader no longer needs `request` for SEO purposes.

> **Why remove it?** Studio-edited SEO is per-page and merchant-controlled. A static override would silently shadow whatever the merchant configures in Studio.

***

## SDK 5-14 error component prop type

`@weaverse/hydrogen` 5.14 narrowed `WeaverseHydrogenRoot`'s `errorComponent` prop to `React.FC<{ error: unknown }>`. If your theme passes a custom error component typed as `{ error?: { message; stack? } }`, TypeScript will now complain. The fix is to accept `unknown` and narrow at runtime:

```tsx theme={null}
export function GenericError({
  error,
}: {
  error: { message: string; stack?: string } | unknown;
}) {
  let description = "We found an error while loading this page.";

  if (error && typeof error === "object" && "message" in error) {
    description += `\n${(error as { message: string }).message}`;
  }

  // …render…
}
```

Apply the same narrowing pattern wherever you read `.stack` or other fields off the error.

***

## Verification checklist

* [ ] `@weaverse/hydrogen` is at `^5.14.0` (or newer) in `package.json` and the installed `node_modules` version matches.
* [ ] Every route you opted in exports a `meta` function returning `getWeaverseSeoMeta(data?.weaverseData)` (or branches per the home/index recipe).
* [ ] Any legacy `seo-overrides.ts` / `customPage` helper is deleted.
* [ ] `typecheck` passes (or only flags pre-existing, unrelated errors).
* [ ] `build` succeeds.
* [ ] Setting a Title/Description in Studio is reflected in the storefront's `<head>` for that page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.