SEO for headless storefronts

import type { Metadata } from 'next'

export async function generateMetadata(props: { params: Promise<{ slug: string }> }): Promise<Metadata> {
  const { slug } = await props.params
  const product = await getProduct(slug) // GET /v1/products/{slug}, or null on 404
  if (!product) return {}

  const description = stripHtml(product.description ?? '').slice(0, 155)
  const image = product.images?.[0]?.url

  return {
    title: `${product.name} | Hearth & Oak`,
    description,
    alternates: { canonical: `https://shop.example.com/products/${product.slug}` },
    openGraph: { title: product.name, description, images: image ? [image] : [] },
  }
}

{
  "data": {
    "handle": "about-us",
    "slug": "about-us",
    "title": "About Hearth & Oak",
    "kind": "page",
    "excerpt": "Furniture and homeware made in Somerset.",
    "seo": {
      "title": "About us | Hearth & Oak",
      "description": "Who we are and how we make our furniture.",
      "image_url": "https://…/workshop.jpg",
      "canonical_url": null,
      "noindex": false
    },
    "published_at": "2026-09-30T08:00:00+00:00",
    "blocks": ["…"]
  }
}

type Money = { amount: number; currency: string }

// For two-decimal currencies such as GBP.
function decimal({ amount }: Money): string {
  const sign = amount < 0 ? '-' : ''
  const abs = Math.abs(amount)
  return `${sign}${Math.trunc(abs / 100)}.${String(abs % 100).padStart(2, '0')}`
}

export function productJsonLd(product: Product, url: string) {
  const variant = product.variants[0]
  const price = variant.pricing.sale_price ?? variant.pricing.price

  return {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    description: stripHtml(product.description ?? ''),
    sku: variant.sku,
    image: product.images.map((image) => image.url),
    offers: {
      '@type': 'Offer',
      url,
      price: decimal(price),
      priceCurrency: price.currency,
      availability: variant.stock > 0 ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock',
    },
  }
}

export function breadcrumbJsonLd(trail: Array<{ name: string; url: string }>) {
  return {
    '@context': 'https://schema.org',
    '@type': 'BreadcrumbList',
    itemListElement: trail.map((item, index) => ({
      '@type': 'ListItem',
      position: index + 1,
      name: item.name,
      item: item.url,
    })),
  }
}

import type { MetadataRoute } from 'next'

const BASE = 'https://shop.example.com'

async function allPages<T>(path: string): Promise<T[]> {
  const items: T[] = []
  for (let page = 1; ; page++) {
    const res = await engineGet<{ data: T[]; meta: { last_page: number } }>(path, new URLSearchParams({ perPage: '100', page: String(page) }))
    items.push(...res.data)
    if (page >= res.meta.last_page) return items
  }
}

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const [products, collections, pages] = await Promise.all([
    allPages<{ slug: string }>('/products'),
    allPages<{ slug: string }>('/collections'),
    allPages<{ slug: string; published_at: string | null }>('/pages'),
  ])

  return [
    ...products.map((p) => ({ url: `${BASE}/products/${p.slug}` })),
    ...collections.map((c) => ({ url: `${BASE}/collections/${c.slug}` })),
    ...pages.map((p) => ({ url: `${BASE}/${p.slug}`, lastModified: p.published_at ?? undefined })),
  ]
}

curl -G https://api.elaraone.app/api/v1/redirects/resolve \
  -H "X-Tenant-Key: $ELARAONE_TENANT_KEY" \
  -H "X-Tenant-Secret: $ELARAONE_TENANT_SECRET" \
  --data-urlencode "path=/products/old-oak-lamp"

{ "data": { "target_url": "/products/oak-desk-lamp", "status_code": 301 } }

import { notFound, permanentRedirect, redirect } from 'next/navigation'

export async function productOrRedirect(slug: string, path: string) {
  const product = await getProduct(slug)
  if (product) return product

  const res = await fetch(`${ENGINE}/redirects/resolve?${new URLSearchParams({ path })}`, { headers: engineHeaders() })
  if (res.ok) {
    const { data } = await res.json()
    if (data.status_code === 301 || data.status_code === 308) permanentRedirect(data.target_url)
    redirect(data.target_url)
  }
  notFound()
}