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

# Quickstart

> Add server-rendered product SEO to a Next.js App Router storefront in four steps.

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](/sdk/next-pages-router), [Remix](/sdk/remix), and [Hydrogen](/sdk/hydrogen) guides.

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    npm install @agentshop/seo
    ```

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

  <Step title="Set your environment variables">
    Add both variables to `.env.local` (and to your deploy platform's environment):

    ```bash .env.local theme={null}
    AGENTSHOP_SEO_URL=https://api.useagentshop.com/api/v1/headless-seo
    AGENTSHOP_API_KEY=<your store API key>
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Add two lines to your product page">
    ```tsx app/products/[handle]/page.tsx theme={null}
    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:

    ```ts app/sitemap.xml/route.ts theme={null}
    import { productSitemapRoute } from "@agentshop/seo/next";

    export const { GET } = productSitemapRoute();
    ```
  </Step>

  <Step title="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](https://search.google.com/test/rich-results) or [validator.schema.org](https://validator.schema.org).
  </Step>
</Steps>

<Tip>
  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 })`.
</Tip>

## Where to go next

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