@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/shopify-headless.md

@@ -1,52 +1,52 @@
----
-title: "Headless Shopify"
-description: "Shopify owns commerce, BetterCMS the editorial: ownership split, product references, cart, freshness and SEO."
----
-
-# Headless Shopify with BetterCMS
-
-**Outcome.** Let editors shape the storefront in BetterCMS while Shopify remains authoritative for saleable products and the buyer transaction. The integration may use Hydrogen/Oxygen or another frontend; inspect the existing stack before choosing code paths.
-
-This complements the [large ecommerce blueprint](site-blueprints.md#large-ecommerce-website), [bindings](bindings.md) and [publishing](publishing.md). Do not assume a BetterCMS Shopify connector or native product picker exists; unless the connected project's tools show one, model product links as validated external ids (below).
-
-## Ownership contract
-
-| Concern | Default owner | BetterCMS treatment |
-|---|---|---|
-| Products, variants, SKUs, price, availability, collections, markets | Shopify | Stable references and optional editorial overlays |
-| Cart, discounts, checkout, orders, customer identity | Shopify | Functional UI and handoff; no copy of private transaction records |
-| Campaign pages, category stories, buying guides, banners, content sections | BetterCMS | Pages, collections, global components, instance overrides |
-| Brand tokens, page composition, nav/footer copy, SEO editorial fields | BetterCMS or frontend design system as established | Bind to rendered leaves; verify publication |
-| Product SEO facts and structured data | Rendered commerce data plus editorial fields | Merge with an explicit field precedence and current price/availability |
-
-Before writing, identify Shopify store and sales channel, Storefront API version, authentication approach, existing frontend, checkout/account flow, market and currency behavior, product handle policy, BetterCMS project/hosting mode, and where current canonical/SEO metadata comes from. Shopify's [Storefront API](https://shopify.dev/docs/api/storefront/latest) provides public catalog, cart, and checkout operations; it does not turn BetterCMS into an order platform.
-
-## Reference and rendering model
-
-Use a stable Shopify product or collection ID as the key in BetterCMS references; store the handle only as a display/routing snapshot. Handles can change. A BetterCMS `ProductEditorial` or `CollectionEditorial` entry can hold hero copy, story sections, buying advice, FAQs, related guides, or campaign placement. A missing editorial overlay must fall back to a valid Shopify-only product or collection page if the merchant intends it to be public.
-
-Use one product template and one collection template unless genuine layout families differ. Render price, compare-at price, availability, variant options, and cart eligibility from a current Shopify response. Do not allow an editor field to override these transactional values. Use a product reference picker only if its existence and ID contract are confirmed; otherwise a validated external-ID field plus preview lookup is safer than a fake internal collection.
-
-Model global promotion bars, nav/footer, category hero, product detail editorial slots, recommendations, and buying guides as BetterCMS components where the editor can see their effects. Define fallback behavior when an overlay is unpublished, a product is not published to the headless channel, a Shopify query fails, or a referenced product was deleted.
-
-## Buyer flow and privacy
-
-The variant selected in the UI must be the exact merchandise ID added to the Shopify cart. Check invalid/expired variants, sold-out changes, quantity limits, discounts, market/currency context, cart persistence, checkout return URLs, and error recovery. Customer accounts and order history use Shopify's current account APIs and authentication, not public BetterCMS content fields. [Shopify cart guidance](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart) · [Customer Account API](https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api)
-
-Keep private Shopify tokens and customer data server-side. Verify the configured token type and exposure boundary rather than treating every Storefront token as a secret. Never put Admin API credentials in browser code.
-
-## Freshness and publication
-
-Content and commerce can publish independently. Define which events revalidate a product or collection route: BetterCMS editorial publish, Shopify product/collection change, handle change, inventory/price change, or market change. Decide cache TTL by data volatility and verify the host's invalidation mechanism. Never put a personalized cart, account page, or customer response in a shared cache. Shopify's [Hydrogen caching guide](https://shopify.dev/docs/storefronts/headless/hydrogen/caching) documents the risk for customer-scoped data.
-
-Deploy a headless frontend through its actual host (SKILL.md invariant 6). For the on-publish refresh, BetterCMS sends a signed revalidation webhook (header `X-BetterCMS-Signature`) to the URL configured on the project; the Next adapter's revalidate route verifies it ([frameworks.md](frameworks.md) Revalidation). A Shopify webhook or polling job may be needed for catalog freshness; verify subscriptions, idempotent processing, and deleted-product handling before relying on it.
-
-## SEO and sitemap contract
-
-Give product and collection routes a single public canonical form. Resolve Shopify handles and BetterCMS editorial slugs without collisions. If variants have selectable URLs, choose one-page versus multi-page variant policy and validate rendered product/variant metadata accordingly. Product JSON-LD must reflect the current purchasable variant, price/currency, and availability; don't publish stale CMS copies. [Google product variant guide](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
-
-Generate sitemap entries for eligible, live product and collection routes plus BetterCMS editorial pages, with no duplicate URLs across providers. Exclude cart, checkout, account, internal search, unpublished overlay-only landing pages, and unwanted filter combinations; a live Shopify product can remain eligible without an editorial overlay. Hydrogen has its own [SEO/sitemap/robots routes](https://shopify.dev/docs/storefronts/headless/hydrogen/seo); if using Hydrogen, reconcile them with BetterCMS page URLs rather than exposing two competing sitemap inventories. Handle `/robots.txt` and sitemap at the actual public host.
-
-## Verification matrix
-
-Test: product with and without editorial overlay; multiple variants; sold-out and unpublished products; handle rename; missing Shopify ID; empty collection; discount and currency/market change; add-to-cart and checkout; account privacy; CMS preview; CMS publish; Shopify update; stale cache; product removal; canonical, schema, sitemap, and redirects. Verify public HTML and a full purchase flow in a safe test environment. Report which systems were live-tested and which assumptions remain unverified.
+---
+title: "Headless Shopify"
+description: "Shopify owns commerce, BetterCMS the editorial: ownership split, product references, cart, freshness and SEO."
+---
+
+# Headless Shopify with BetterCMS
+
+**Outcome.** Let editors shape the storefront in BetterCMS while Shopify remains authoritative for saleable products and the buyer transaction. The integration may use Hydrogen/Oxygen or another frontend; inspect the existing stack before choosing code paths.
+
+This complements the [large ecommerce blueprint](site-blueprints.md#large-ecommerce-website), [bindings](bindings.md) and [publishing](publishing.md). Do not assume a BetterCMS Shopify connector or native product picker exists; unless the connected project's tools show one, model product links as validated external ids (below).
+
+## Ownership contract
+
+| Concern | Default owner | BetterCMS treatment |
+|---|---|---|
+| Products, variants, SKUs, price, availability, collections, markets | Shopify | Stable references and optional editorial overlays |
+| Cart, discounts, checkout, orders, customer identity | Shopify | Functional UI and handoff; no copy of private transaction records |
+| Campaign pages, category stories, buying guides, banners, content sections | BetterCMS | Pages, collections, global components, instance overrides |
+| Brand tokens, page composition, nav/footer copy, SEO editorial fields | BetterCMS or frontend design system as established | Bind to rendered leaves; verify publication |
+| Product SEO facts and structured data | Rendered commerce data plus editorial fields | Merge with an explicit field precedence and current price/availability |
+
+Before writing, identify Shopify store and sales channel, Storefront API version, authentication approach, existing frontend, checkout/account flow, market and currency behavior, product handle policy, BetterCMS project/hosting mode, and where current canonical/SEO metadata comes from. Shopify's [Storefront API](https://shopify.dev/docs/api/storefront/latest) provides public catalog, cart, and checkout operations; it does not turn BetterCMS into an order platform.
+
+## Reference and rendering model
+
+Use a stable Shopify product or collection ID as the key in BetterCMS references; store the handle only as a display/routing snapshot. Handles can change. A BetterCMS `ProductEditorial` or `CollectionEditorial` entry can hold hero copy, story sections, buying advice, FAQs, related guides, or campaign placement. A missing editorial overlay must fall back to a valid Shopify-only product or collection page if the merchant intends it to be public.
+
+Use one product template and one collection template unless genuine layout families differ. Render price, compare-at price, availability, variant options, and cart eligibility from a current Shopify response. Do not allow an editor field to override these transactional values. Use a product reference picker only if its existence and ID contract are confirmed; otherwise a validated external-ID field plus preview lookup is safer than a fake internal collection.
+
+Model global promotion bars, nav/footer, category hero, product detail editorial slots, recommendations, and buying guides as BetterCMS components where the editor can see their effects. Define fallback behavior when an overlay is unpublished, a product is not published to the headless channel, a Shopify query fails, or a referenced product was deleted.
+
+## Buyer flow and privacy
+
+The variant selected in the UI must be the exact merchandise ID added to the Shopify cart. Check invalid/expired variants, sold-out changes, quantity limits, discounts, market/currency context, cart persistence, checkout return URLs, and error recovery. Customer accounts and order history use Shopify's current account APIs and authentication, not public BetterCMS content fields. [Shopify cart guidance](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart) · [Customer Account API](https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api)
+
+Keep private Shopify tokens and customer data server-side. Verify the configured token type and exposure boundary rather than treating every Storefront token as a secret. Never put Admin API credentials in browser code.
+
+## Freshness and publication
+
+Content and commerce can publish independently. Define which events revalidate a product or collection route: BetterCMS editorial publish, Shopify product/collection change, handle change, inventory/price change, or market change. Decide cache TTL by data volatility and verify the host's invalidation mechanism. Never put a personalized cart, account page, or customer response in a shared cache. Shopify's [Hydrogen caching guide](https://shopify.dev/docs/storefronts/headless/hydrogen/caching) documents the risk for customer-scoped data.
+
+Deploy a headless frontend through its actual host (SKILL.md invariant 6). For the on-publish refresh, BetterCMS sends a signed revalidation webhook (header `X-BetterCMS-Signature`) to the URL configured on the project; the Next adapter's revalidate route verifies it ([frameworks.md](frameworks.md) Revalidation). A Shopify webhook or polling job may be needed for catalog freshness; verify subscriptions, idempotent processing, and deleted-product handling before relying on it.
+
+## SEO and sitemap contract
+
+Give product and collection routes a single public canonical form. Resolve Shopify handles and BetterCMS editorial slugs without collisions. If variants have selectable URLs, choose one-page versus multi-page variant policy and validate rendered product/variant metadata accordingly. Product JSON-LD must reflect the current purchasable variant, price/currency, and availability; don't publish stale CMS copies. [Google product variant guide](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
+
+Generate sitemap entries for eligible, live product and collection routes plus BetterCMS editorial pages, with no duplicate URLs across providers. Exclude cart, checkout, account, internal search, unpublished overlay-only landing pages, and unwanted filter combinations; a live Shopify product can remain eligible without an editorial overlay. Hydrogen has its own [SEO/sitemap/robots routes](https://shopify.dev/docs/storefronts/headless/hydrogen/seo); if using Hydrogen, reconcile them with BetterCMS page URLs rather than exposing two competing sitemap inventories. Handle `/robots.txt` and sitemap at the actual public host.
+
+## Verification matrix
+
+Test: product with and without editorial overlay; multiple variants; sold-out and unpublished products; handle rename; missing Shopify ID; empty collection; discount and currency/market change; add-to-cart and checkout; account privacy; CMS preview; CMS publish; Shopify update; stale cache; product removal; canonical, schema, sitemap, and redirects. Verify public HTML and a full purchase flow in a safe test environment. Report which systems were live-tested and which assumptions remain unverified.