Quickstart - AgentShop

This quickstart wires product metadata, product JSON-LD, and a sitemap into a Next.js App Router storefront. Other frameworks follow the same shape — see the Pages Router, Remix, and Hydrogen guides.

Install the package

npm install @agentshop/seo

The package is ESM-only and requires Node 18+. All peer dependencies are optional — nothing extra is pulled in.

Set your environment variables

Add both variables to .env.local (and to your deploy platform’s environment):

.env.local

AGENTSHOP_SEO_URL=https://api.useagentshop.com/api/v1/headless-seo
AGENTSHOP_API_KEY=<your store API key>

Find your store API key (ask_…) in the AgentShop dashboard under Settings → API Keys — one key per store. It’s a secret: keep it in a server-side env var only (never a NEXT_PUBLIC_* variable or client code). The SDK uses it only on the server, so nothing is exposed to the browser.

Add two lines to your product page

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() returns a ready generateMetadata that renders the title, meta description, canonical, Open Graph, and Twitter tags. <ProductJsonLd> is an async server component that renders the Product + BreadcrumbList JSON-LD script. Both work with Next 14 (sync params) and Next 15/16 (Promise params) — no version-specific code needed.Optionally add the sitemap route:

app/sitemap.xml/route.ts

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

export const { GET } = productSitemapRoute();

Verify

Open a product page and use View Source (Ctrl+U / Cmd+Option+U) — not the DevTools Elements panel. DevTools shows the hydrated DOM; crawlers see the initial HTML, which is what View Source shows.You should see:

A real <title> and <meta name="description"> from your Shopify SEO fields
<link rel="canonical">, og:*, and twitter:* tags
A <script type="application/ld+json"> block with Product and BreadcrumbList

Then validate the structured data with the Google Rich Results Test or validator.schema.org.

The default fetch timeout is 3 seconds — right for the warm production endpoint. If you’re testing against a cold or local backend and tags don’t appear, raise it: createProductMetadata({ timeoutMs: 15000 }).

Where to go next

Add collection pages and the site-level JSON-LD on your home page (App Router).
Read Concepts for how bundles, caching, and graceful degradation work.
Something not rendering? See Troubleshooting.

​Where to go next

Where to go next