Next.js

Next.js is the lowest-wiring server deployment: one pure public config, one server-bound SEO instance, one proxy/middleware for the discovery surfaces, and one Client Component for agent tools.

1. Create the shared public config

src/lib/commerce-seo.config.ts

import { defineCommerceSeoConfig } from "@commercengine/seo/config";

export const commerceSeo = defineCommerceSeoConfig({
  site: {
    name: "Acme",
    url: "https://acme.example",
    brandName: "Acme",
    description: "Acme's official online store.",
    locale: "en_US",
  },
  routes: {
    productBase: "/product",
    categoryBase: "/category",
  },
});

export const { site, routes } = commerceSeo;

2. Create the server-bound SEO instance

src/lib/seo.ts

import { createCommerceSeo } from "@commercengine/seo";
import { commerceSeo } from "@/lib/commerce-seo.config";
import { storefront } from "@/lib/storefront";

export const seo = createCommerceSeo({ ...commerceSeo, storefront });

Client Components must not import @/lib/seo. Import site and routes from commerce-seo.config.ts. The SEO instance holds the storefront and belongs on the server/build side of the bundle boundary.

3. Serve every discovery surface from one proxy

Next.js 16 uses proxy.ts. On Next.js 15, export the same handler from middleware.ts.

src/proxy.ts

import { createNextjsSeoProxy } from "@commercengine/seo/nextjs/server";
import { seo } from "@/lib/seo";

export default createNextjsSeoProxy(seo, {
  robots: true,
  sitemap: true,
});

export const config = {
  matcher: [
    "/product/:path*",
    "/category/:path*",
    "/search",
    "/search.md",
    "/llms.txt",
    "/sitemap.md",
    "/robots.txt",
    "/sitemap.xml",
    "/sitemap/:path*",
  ],
};

This one handler owns:

product/category Markdown mirrors
same-URL Markdown negotiation
/llms.txt
/sitemap.md
robots.txt
sitemap.xml and shards beyond the URL limit

You do not need eleven separate App Router route files.

Static/prerendered Next output

If the deployment has no Next server at request time, use the same prebuild strategy as a React/Vite app and write assets into public/ with @commercengine/seo/build.

4. Generate native Next metadata

Use the public storefront inside generateMetadata:

app/product/[slug]/page.tsx

import { createProductMetadata } from "@commercengine/seo/nextjs";
import type { Metadata } from "next";
import { seo } from "@/lib/seo";
import { storefront } from "@/lib/storefront";

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const { data } = await storefront
    .publicStorefront()
    .catalog.getProductDetail({ product_id: slug });

  if (!data?.product) return { title: "Product Not Found" };
  return createProductMetadata(seo, data.product);
}

If public/CMS slugs differ from CE slugs, resolve the route first:

const identifier = await seo.resolveProductRoute(slug);
if (!identifier) return { title: "Product Not Found" };

Category pages use createCategoryMetadata().

5. Render product JSON-LD and breadcrumbs

Next Metadata covers normal head metadata. Render JSON-LD in the page body:

const productSchema = await seo.productJsonLd(product);

const category = product.categories?.[0];
const [productUrl, categoryUrl] = await Promise.all([
  seo.productUrl(product),
  category ? seo.categoryUrl(category) : Promise.resolve(null),
]);

const breadcrumb = seo.breadcrumbJsonLd([
  { name: "Home", url: seo.config.site.url },
  ...(category && categoryUrl ? [{ name: category.name, url: categoryUrl }] : []),
  { name: product.name, url: productUrl ?? seo.config.site.url },
]);

return (
  <>
    {[productSchema, breadcrumb].map((schema) => (
      <script
        key={schema["@type"]}
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(schema).replace(/</g, "\\u003c"),
        }}
      />
    ))}
    {/* page */}
  </>
);

You can use your own safe JSON-LD serializer or the package serializer. Do not emit a second hand-written Product schema for the same item.

Product-specific Open Graph properties

productOpenGraphTags() from @commercengine/seo/nextjs exposes product Open Graph fields that do not map cleanly into the generic Next Metadata shape:

import { productOpenGraphTags } from "@commercengine/seo/nextjs";

{productOpenGraphTags(product).map((tag) => (
  <meta
    key={`${tag.property}:${tag.content}`}
    property={tag.property}
    content={tag.content}
  />
))}

6. Register WebMCP in a root Client Component

src/components/AgentTools.tsx

"use client";

import { createHostedCheckoutBridge } from "@commercengine/ai/checkout";
import { registerCommerceWebMcp } from "@commercengine/ai/webmcp";
import { getCheckout } from "@commercengine/checkout";
import { useRouter } from "next/navigation";
import { useEffect } from "react";
import { routes, site } from "@/lib/commerce-seo.config";
import { storefront } from "@/lib/storefront";

export function AgentTools() {
  const router = useRouter();

  useEffect(() => {
    let registration: AbortController | null = null;
    let cancelled = false;

    void registerCommerceWebMcp({
      storefront,
      siteUrl: site.url,
      routes,
      checkout: createHostedCheckoutBridge({ getState: () => getCheckout() }),
      navigation: { navigate: (url) => router.push(url) },
      diagnostics:
        process.env.NODE_ENV === "development"
          ? (event) => console.info("[commerce-ai]", event.code, event.message ?? "")
          : undefined,
    }).then((controller) => {
      if (cancelled) controller?.abort();
      else registration = controller;
    });

    return () => {
      cancelled = true;
      registration?.abort();
    };
  }, [router]);

  return null;
}

Mount <AgentTools /> once in the root layout. It returns no UI.

Do not wait for storefront.bootstrap() before registering the tools. Registration only declares them; session-dependent tools already report a retryable failure until the browser session is ready.

7. Hosted Checkout remains human-controlled

If you already use Hosted Checkout, keep its normal root bootstrap. The AI bridge only exposes open_cart, open_checkout, and optionally open_login; cart mutations themselves use the authenticated Storefront SDK. See Hosted Checkout + Next.js for the session synchronization pattern.

Production checklist

proxy.ts matcher includes the .md, robots, sitemap, and discovery paths you enable
generateMetadata uses publicStorefront() rather than a live session accessor
PDP has exactly one product schema plus its breadcrumb schema
Client AgentTools imports commerce-seo.config, not the server SEO module
registration?.abort() runs on unmount
development console contains the Commerce AI registration diagnostic
direct requests to /product/example.md, /llms.txt, and /sitemap.xml return successfully

Reference starter

Full Next.js production storefront with both packages wired.

Getting Started

Framework Guides

Reference

1. Create the shared public config

2. Create the server-bound SEO instance

3. Serve every discovery surface from one proxy

Static/prerendered Next output

4. Generate native Next metadata

Product-specific Open Graph properties

6. Register WebMCP in a root Client Component

7. Hosted Checkout remains human-controlled

Production checklist

Reference starter

​1. Create the shared public config

​2. Create the server-bound SEO instance

​3. Serve every discovery surface from one proxy

​Static/prerendered Next output

​4. Generate native Next metadata

​5. Render product JSON-LD and breadcrumbs

​Product-specific Open Graph properties

​6. Register WebMCP in a root Client Component

​7. Hosted Checkout remains human-controlled

​Production checklist

Reference starter

1. Create the shared public config

2. Create the server-bound SEO instance

3. Serve every discovery surface from one proxy

Static/prerendered Next output

4. Generate native Next metadata

5. Render product JSON-LD and breadcrumbs

Product-specific Open Graph properties

6. Register WebMCP in a root Client Component

7. Hosted Checkout remains human-controlled

Production checklist