j4flmao/agent-skills/headless

Headless E-commerce

Purpose

Build a custom storefront on top of a commerce backend (Shopify, commercetools, BigCommerce, Saleor, Medusa) while keeping catalog pages fast and cacheable and keeping personalized data (cart, customer) uncached and correct. Checkout usually stays on the platform's hosted checkout.

Agent Protocol

Trigger

"headless commerce", "hydrogen", "storefront api", "oxygen", "composable commerce", "headless shopify", "storefront caching".

Input Context

• Commerce platform and plan; whether hosted checkout is required.
• Frontend framework preference (Hydrogen on React Router, Next.js, Astro).
• Catalog size, update frequency, markets/currencies.

Output Artifact

Architecture + data-fetching/caching plan; route loader code on request.

Response Format

Platform: {backend}  Frontend: {framework}  Hosting: {Oxygen|Vercel|Cloudflare|...}
Data -> cache: {products: long, collections: short, cart/customer: none}
Checkout: {hosted|custom}
Risks: {list}

When Headless Is Worth It

Caching by Data Type

Hydrogen Loader (React Router based)

Hydrogen queries use template strings tagged with #graphql (enables codegen and editor support). Cache strategy is passed per query.

import { CacheLong } from '@shopify/hydrogen';
import type { LoaderFunctionArgs } from 'react-router';
const PRODUCT_QUERY = `#graphql
  query Product($handle: String!, $country: CountryCode, $language: LanguageCode)
    @inContext(country: $country, language: $language) {
    product(handle: $handle) {
      id
      title
      descriptionHtml
      selectedOrFirstAvailableVariant {
        id
        availableForSale
        price { amount currencyCode }
      }
    }
  }
` as const;
export async function loader({ params, context }: LoaderFunctionArgs) {
  if (!params.handle) throw new Response('Missing product handle', { status: 400 });
  const { product } = await context.storefront.query(PRODUCT_QUERY, {
    variables: { handle: params.handle },
    cache: CacheLong(),
  });
  if (!product) throw new Response(`Product not found: ${params.handle}`, { status: 404 });
  return { product };
}

Older Hydrogen versions import loader types from @shopify/remix-oxygen; check the project's package.json before generating imports.

Cart

• Use the Storefront API Cart object (cartCreate, cartLinesAdd, cartLinesUpdate); persist cart ID in a cookie. Hydrogen's createCartHandler wraps this.
• Never cache cart reads; perform cart mutations in actions (POST), not loaders.
• Send the shopper to cart.checkoutUrl for hosted checkout.

Query Discipline

• Colocate GraphQL fragments with the components that render them; request only rendered fields.
• Paginate with first/after cursors; avoid first: 250 everywhere.
• Storefront API rate limits are generous but not infinite — cache at the edge and avoid N+1 per product card (fetch lists in one query).
• Use @inContext(country, language) for market-specific pricing/translations.

Deployment

• Hydrogen deploys to Oxygen (Shopify's hosting) or any Workers-compatible/Node host.
• Set Cache-Control headers deliberately on documents; personalized routes private, no-store.
• Preserve SEO: canonical URLs, hreflang for markets, structured data (Product, Offer), sitemap generation.

Anti-Patterns

Checklist

• [ ] Cache strategy defined for every query
• [ ] No personalized data in cached responses
• [ ] Product/collection 404s handled
• [ ] Market/locale context passed to queries
• [ ] Structured data + canonical tags on product pages
• [ ] Hosted checkout via checkoutUrl

References

• skills/ecommerce/checkout-cart/references/cart-architecture.md
• skills/ecommerce/checkout-cart/references/checkout-ux.md