Skip to main content

BigCommerce headless (Catalyst, Alokai)

Read this first. On a headless BigCommerce storefront, Clione writes the data and your storefront code has to render it. Nothing Clione installs reaches a Catalyst or Alokai front end on its own. This page says what has been verified and what hasn't.

On a Stencil theme, Clione publishes its JSON-LD through a BigCommerce widget that BigCommerce renders into the page. A headless storefront (Catalyst, Alokai, any Next.js or Nuxt front end on BigCommerce's APIs) never renders those widgets. What a headless storefront can read instead is product metafields.

What Clione writes when you publish a product​

Every time you publish a product on a BigCommerce store, Clione writes the Stencil widget and three product metafields, whether your storefront is headless or not:

NamespaceKeyValueWritten when
clionejsonldThe same JSON-LD @graph the Stencil widget carries: Organization, WebSite, BreadcrumbList, Product, and FAQPage when the product has FAQsEvery product publish
globaltitle_tagThe meta title Clione just wroteThe publish included the meta title
globaldescription_tagThe meta description Clione just wroteThe publish included the meta description

The metafields are created with BigCommerce's read_and_sf_access permission, the setting BigCommerce provides for metafields a storefront reads through its Storefront GraphQL API.

Writing them never blocks the publish: if a metafield write fails, the publish still reports the Stencil widget as written.

What your storefront has to do​

  1. Ask for the metafields. Your storefront's product query has to request namespace clione, key jsonld, and namespace global, keys title_tag and description_tag. A query that doesn't ask for them gets nothing.
  2. Render them server-side. Print the JSON-LD as a <script type="application/ld+json"> in the HTML your server returns, and the title and description as the page's <title> and <meta name="description">. AI crawlers don't run JavaScript, so a tag added in the browser doesn't count.

The @clione/seo SDK reads exactly these three metafields: extractSignals() takes a product object that already carries them and returns the JSON-LD, title and description. It has a Nuxt adapter for Alokai storefronts and a React adapter for Next.js. It does not change your product query; asking for the metafields is still your code's job.

Verified, and not verified​

Verified:

  • Clione's code writes the three metafields on every product publish, with read_and_sf_access.
  • On a real BigCommerce store (our fixture store), a published product carries the Clione metafields.
  • The metafield names the SDK looks for are the ones Clione writes.

Not verified:

  • That a headless storefront reads them back. The read-back half has not been run against a real Catalyst or Alokai storefront. Our Catalyst test storefront returned an error when we tried.
  • That BigCommerce exposes them through the Storefront GraphQL API on a real store. It is the documented behaviour of read_and_sf_access, not something we have observed.
  • That Alokai's BigCommerce connector requests product metafields by default. Assume it doesn't, and add them to your query.
  • Any end-to-end run. There is no automated test of Clione on a headless BigCommerce storefront.

What is not there​

  • Products only. Categories and pages get no metafields: on a headless BigCommerce storefront there is nothing for them to read.
  • No packaged Catalyst or Alokai module. The SDK is a general-purpose library your developers call from their own pages. There is nothing to install that hooks into the storefront by itself, the way the widget does on Stencil or the app embed does on Shopify.

Check it yourself​

After publishing a product, fetch its page with a crawler user agent and look for the JSON-LD in the raw HTML:

curl -sSL -A "Mozilla/5.0 (compatible; Googlebot/2.1)" "https://your-store.example/product-url/" -o /tmp/p.html
grep -c '"@type":"Product"' /tmp/p.html

Zero means your storefront isn't rendering the metafield server-side yet, whatever Clione wrote.

See also: Platform capabilities · Headless — Next.js.