SvelteKit

SvelteKit can run with a request-time server or as adapter-static. Use the server hook when requests reach SvelteKit in production; use the prebuild asset writer when the deployment is static.

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;

Keep the SEO instance in server/build-safe code:

src/lib/server/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 });

2. Build product/category head data in load

src/routes/product/[slug]/+page.server.ts

import { createSvelteKitProductHead } from "@commercengine/seo/sveltekit";
import { seo } from "$lib/server/seo";
import { storefront } from "$lib/storefront";

export async function load({ params }) {
  const { data, error, response } = await storefront
    .publicStorefront()
    .catalog.getProductDetail({ product_id: params.slug });

  if (error && response.status !== 404) {
    throw new Error(error.message);
  }

  const product = data?.product ?? null;
  return {
    product,
    seoHead: product ? await createSvelteKitProductHead(seo, product) : undefined,
  };
}

Render the model from <svelte:head>:

src/routes/product/[slug]/+page.svelte

<script lang="ts">
  let { data } = $props();
</script>

{#if data.seoHead}
  <svelte:head>
    <title>{data.seoHead.title}</title>
    {#each data.seoHead.meta as tag}
      {#if tag.property}
        <meta property={tag.property} content={tag.content} />
      {:else}
        <meta name={tag.name} content={tag.content} />
      {/if}
    {/each}
    {#each data.seoHead.links as tag}
      <link rel={tag.rel} href={tag.href} type={tag.type} />
    {/each}
    {#each data.seoHead.scripts as script}
      {@html `<script type="${script.type}">${script.content}</script>`}
    {/each}
  </svelte:head>
{/if}

Gate site-wide Open Graph/Twitter fallback tags when page.data.seoHead exists. Svelte does not automatically deduplicate a layout’s generic og:title or og:image against page-specific values.

As with other frameworks, add breadcrumbs separately using seo.productUrl() and seo.categoryUrl().

3A. Server deployment: use the SvelteKit handle

src/hooks.server.ts

import { createSvelteKitSeoHandle } from "@commercengine/seo/sveltekit/server";
import { seo } from "$lib/server/seo";

export const handle = createSvelteKitSeoHandle(seo, {
  robots: true,
  sitemap: true,
});

If your project already has a handle, compose the SEO handle with SvelteKit’s sequence() helper rather than replacing the existing hook. The handler owns Markdown mirrors, content negotiation, llms.txt, sitemap.md, robots, and XML sitemap routes.

3B. `adapter-static`: prebuild into `static/`

Static hosting cannot inspect Accept at runtime and cannot build arbitrary /search.md?q=... queries. Generate explicit discovery files before the SvelteKit build: Reuse the shared commerceSeo declaration from step 1 and load local env files before SvelteKit/Vite starts. Running the prebuild as TypeScript keeps that config as a single source of truth:

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 storefront credentials");

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

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

package.json

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

Leave indexable unset in this shared script. Deployment detection then keeps preview builds non-indexable and marks only proven production deployments indexable. Generated SEO files should be gitignored.

Vercel and `adapter-static`

SvelteKit static output can emit route files such as privacy-policy.html. On Vercel, enable clean URLs so sitemap-advertised extensionless routes resolve:

vercel.json

{
  "cleanUrls": true
}

If /foo.html works but /foo returns 404 in production, the Svelte build succeeded and only host routing is missing.

4. Register WebMCP in root `onMount`

src/routes/+layout.svelte

<script lang="ts">
  import { goto } from "$app/navigation";
  import { onMount } from "svelte";

  let agentTools: AbortController | null = null;

  onMount(() => {
    let cancelled = false;

    // Your normal storefront/bootstrap can run in parallel.
    void initStorefront();

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

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

      if (cancelled) registration?.abort();
      else agentTools = registration;
    })();

    return () => {
      cancelled = true;
      agentTools?.abort();
    };
  });
</script>

Keep the cleanup return last in onMount. Code placed after it is unreachable but still typechecks and builds, which can leave a storefront with no agent tools and no compiler error. Development diagnostics are the fastest way to catch this.

Production checklist

choose server hook or static prebuild from the adapter/deployment target
static build outputs go to static/, not public/
vercel.json uses cleanUrls for adapter-static deployments on Vercel
generic layout metadata yields to page seoHead
root onMount actually reaches the WebMCP registration block
development diagnostics prove registration ran
cleanup aborts the registration
production deep links and .md mirrors both return 200

Reference starter

Full SvelteKit adapter-static storefront using both packages.

Getting Started

Framework Guides

Reference

1. Shared config and SEO instance

2. Build product/category head data in load

3A. Server deployment: use the SvelteKit handle

3B. `adapter-static`: prebuild into `static/`

Vercel and `adapter-static`

4. Register WebMCP in root `onMount`

Production checklist

Reference starter

​1. Shared config and SEO instance

​2. Build product/category head data in load

​3A. Server deployment: use the SvelteKit handle

​3B. adapter-static: prebuild into static/

​Vercel and adapter-static

​4. Register WebMCP in root onMount

​Production checklist

Reference starter

1. Shared config and SEO instance

2. Build product/category head data in load

3A. Server deployment: use the SvelteKit handle

3B. `adapter-static`: prebuild into `static/`

Vercel and `adapter-static`

4. Register WebMCP in root `onMount`

Production checklist