Astro

Astro can be a server application or a static site. Choose the SEO serving mechanism from the deployment mode, not from the Astro logo:

output: "server" or on-demand SEO routes → mount one middleware
default/static output → write SEO assets into public/ before astro build

Both modes use the same head helpers and the same client-side AI registration.

1. Shared config and SEO instance

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",
    locale: "en_US",
  },
  routes: { productBase: "/product", categoryBase: "/category" },
});

export const { site, routes } = commerceSeo;

src/lib/seo.ts

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

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

2. Render Astro-native head data

src/pages/product/[slug].astro

---
import { createAstroProductHead } from "@commercengine/seo/astro";
import { seo } from "../../lib/seo";
import { publicSdk } from "../../lib/storefront";

const { slug } = Astro.params;
const { data } = await publicSdk.catalog.getProductDetail({ product_id: slug! });
const product = data?.product;
const seoHead = product ? await createAstroProductHead(seo, product) : undefined;
---

<Layout seoHead={seoHead} noindex={!product}>
  <!-- page -->
</Layout>

Your layout should render seoHead.title, seoHead.meta, seoHead.links, and seoHead.scripts. Do not also render generic product/page Open Graph tags when seoHead is present.

---
import { serializeJsonLd } from "@commercengine/seo";

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

const breadcrumb = product
  ? 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 },
    ])
  : null;
---

{breadcrumb && (
  <script is:inline type="application/ld+json" set:html={serializeJsonLd(breadcrumb)} />
)}

Use seo.productUrl() and seo.categoryUrl() for breadcrumbs. Hard-coded /product/ or /category/ concatenation breaks as soon as a CMS or route resolver changes the public URL.

3A. Server deployment: mount middleware

src/middleware.ts

import { createAstroSeoMiddleware } from "@commercengine/seo/astro/server";
import { seo } from "./lib/seo";

export const onRequest = createAstroSeoMiddleware(seo, {
  robots: true,
  sitemap: true,
});

The middleware handles Markdown mirrors, content negotiation, llms.txt, sitemap.md, robots, and XML sitemap routes. It delegates unrelated requests without adding unnecessary Vary: Accept cache keys. Use this only when those requests actually reach an Astro server in production.

3B. Static deployment: generate physical files

For Astro’s default static output, write the assets into public/ before the build: Use the same pure SEO config from step 1 rather than copying site identity or route bases into the build script. Run the prebuild as TypeScript and load local env files explicitly because this command runs before Astro starts:

pnpm add -D tsx dotenv

scripts/generate-seo-assets.ts

import { existsSync } from "node:fs";
import { createCommerceSeo } from "@commercengine/seo";
import { writeCommerceSeoAssets } from "@commercengine/seo/build";
import { createStorefront, Environment } from "@commercengine/storefront";
import { config as loadEnvFiles } from "dotenv";
import { commerceSeo } from "../src/lib/commerce-seo.config";

const envFiles = [
  ".env.production.local",
  ".env.local",
  ".env.production",
  ".env",
].filter(existsSync);
if (envFiles.length) loadEnvFiles({ path: envFiles });

const storeId = process.env.PUBLIC_STORE_ID;
const apiKey = process.env.PUBLIC_API_KEY;
if (!storeId || !apiKey) {
  throw new Error("[seo] missing PUBLIC_STORE_ID / PUBLIC_API_KEY");
}

const seo = createCommerceSeo({
  ...commerceSeo,
  storefront: createStorefront({
    storeId,
    apiKey,
    environment:
      process.env.PUBLIC_CE_ENV === "production"
        ? Environment.Production
        : Environment.Staging,
  }),
});

await writeCommerceSeoAssets(seo, { outDir: "public" });

package.json

{
  "scripts": {
    "build": "tsx scripts/generate-seo-assets.ts && astro build"
  }
}

Do not keep indexable: true in a shared build script. Leaving it unset preserves the package’s deployment detection, so preview CI builds stay non-indexable while a proven production deployment becomes indexable automatically. The generated files bypass Astro’s file-router priority entirely.

Do not implement static .md mirrors as a catch-all Astro route. A concrete /product/[slug] route can claim /product/shoe.md before the catch-all gets a chance to serve it.

4. Register agent tools with the client runtime

With View Transitions, the document changes without a normal full-page reload. Register on astro:page-load and clean up registrations across transitions.

src/lib/client-runtime.ts

let agentTools: AbortController | null = null;

async function registerAgentTools() {
  const [
    { registerCommerceWebMcp },
    { createHostedCheckoutBridge },
    { getCheckout },
    { storefront },
    { routes, site },
  ] = await Promise.all([
    import("@commercengine/ai/webmcp"),
    import("@commercengine/ai/checkout"),
    import("@commercengine/checkout"),
    import("./storefront-client"),
    import("./commerce-seo.config"),
  ]);

  agentTools?.abort();
  agentTools = await registerCommerceWebMcp({
    storefront,
    siteUrl: site.url,
    routes,
    checkout: createHostedCheckoutBridge({ getState: () => getCheckout() }),
    navigation: { navigate: (url) => { window.location.href = url; } },
    diagnostics: import.meta.env.DEV
      ? (event) => console.info("[commerce-ai]", event.code, event.message ?? "")
      : undefined,
  });
}

document.addEventListener("astro:page-load", () => void registerAgentTools());
document.addEventListener("astro:before-swap", () => agentTools?.abort());

If your app has no View Transitions, registering once from a client island/runtime bootstrap is sufficient.

Production checklist

Astro output mode matches the SEO serving mechanism
static deployments generate files into public/
server deployments mount createAstroSeoMiddleware
page layout yields generic social defaults whenever page-specific seoHead exists
breadcrumb URLs come from route resolvers
View Transition navigation does not accumulate duplicate WebMCP registrations
development diagnostics fire on every starter page load where registration is expected

Reference starter

Static Astro production pattern with page head data, prebuilt discovery assets, and WebMCP registration.

Getting Started

Framework Guides

Reference

1. Shared config and SEO instance

2. Render Astro-native head data

3A. Server deployment: mount middleware

3B. Static deployment: generate physical files

4. Register agent tools with the client runtime

Production checklist

Reference starter

​1. Shared config and SEO instance

​2. Render Astro-native head data

​Add the breadcrumb separately

​3A. Server deployment: mount middleware

​3B. Static deployment: generate physical files

​4. Register agent tools with the client runtime

​Production checklist

Reference starter

1. Shared config and SEO instance

2. Render Astro-native head data

Add the breadcrumb separately

3A. Server deployment: mount middleware

3B. Static deployment: generate physical files

4. Register agent tools with the client runtime

Production checklist