Next.js App Router

The App Router adapter is the most complete integration: product and collection metadata, site-level JSON-LD, and a sitemap route handler. Import everything from @agentshop/seo/next. All helpers read AGENTSHOP_API_KEY and AGENTSHOP_SEO_URL from the environment, cache with ISR (revalidate: 3600) by default, and return nothing on any failure — your page never 500s because of SEO. See Concepts.

Product pages

app/products/[handle]/page.tsx

import { createProductMetadata, ProductJsonLd } from "@agentshop/seo/next";

export const generateMetadata = createProductMetadata();

export default function Page({ params }: { params: { handle: string } }) {
  return (
    <main>
      {/* …your product UI… */}
      <ProductJsonLd handle={params.handle} />
    </main>
  );
}

createProductMetadata(config?) is a factory returning a ready generateMetadata. Use the factory whenever you pass config — it avoids colliding with Next’s positional generateMetadata(props, parent) signature. If you need zero config, you can also export generateProductMetadata directly.
<ProductJsonLd handle config? /> is an async server component: it renders the <script type="application/ld+json"> with Product + BreadcrumbList, or nothing if the bundle is unavailable.
Both support Next 14 (sync params) and Next 15/16 (Promise params).

On the App Router, og:type is deliberately omitted: "product" isn’t in Next’s typed Metadata Open Graph union and throws at runtime. All other Open Graph tags render normally with property="og:*". The Pages Router, Remix, and Hydrogen adapters do emit og:type=product (raw meta tags accept it).

Collection pages

app/collections/[handle]/page.tsx

import { createCollectionMetadata, CollectionJsonLd } from "@agentshop/seo/next";

export const generateMetadata = createCollectionMetadata();

export default function Page({ params }: { params: { handle: string } }) {
  return (
    <main>
      <CollectionJsonLd handle={params.handle} />
    </main>
  );
}

Renders CollectionPage + ItemList + breadcrumb JSON-LD, with og:type=website semantics in the bundle. See Collection JSON-LD.

Home page (site-level JSON-LD)

app/page.tsx

import { SiteJsonLd } from "@agentshop/seo/next";

export default function Home() {
  return (
    <main>
      {/* …your home UI… */}
      <SiteJsonLd />
    </main>
  );
}

Renders the Organization + WebSite (+ FAQPage when your store has published FAQs) graph. Inject it once, on the home page only. See Site-level JSON-LD.

Sitemap

app/sitemap.xml/route.ts

import { productSitemapRoute } from "@agentshop/seo/next";

export const { GET } = productSitemapRoute();

Returns 200 with the XML, or 502 with an empty body when the sitemap is unavailable. See Sitemap.

Passing configuration

Every factory and component accepts an optional SeoClientConfig:

export const generateMetadata = createProductMetadata({
  timeoutMs: 15000,                              // e.g. cold/local backend
  fetchOptions: { next: { revalidate: 60 } },    // override the default 3600s ISR
});

<ProductJsonLd handle={params.handle} config={{ timeoutMs: 15000 }} />

Environment variables (AGENTSHOP_API_KEY, AGENTSHOP_SEO_URL) are used for anything you don’t pass explicitly. AGENTSHOP_API_KEY is a secret — keep it in a server-side env var, never a NEXT_PUBLIC_* one. Every helper here runs on the server, so the key never reaches the browser.

Full export list

See the Next.js API reference for exact signatures of generateProductMetadata, createProductMetadata, generateCollectionMetadata, createCollectionMetadata, ProductJsonLd, CollectionJsonLd, SiteJsonLd, productSitemapRoute, and toNextMetadata.

​Product pages

​Collection pages

​Home page (site-level JSON-LD)

​Sitemap

​Passing configuration

​Full export list

Product pages

Collection pages

Home page (site-level JSON-LD)

Sitemap

Passing configuration

Full export list