--- name: bc-headless-f33e5d7d7b44 description: > Build headless commerce with BigCommerce — Catalyst (Next.js reference storefront), GraphQL Storefront API, server-side APIs, embedded checkout, and headless architecture patterns. Use when building decoupled storefronts or integrating BigCommerce as a headless backend. --- # BigCommerce Headless Commerce ## Before writing code **Fetch live docs**: 1. Fetch `https://www.catalyst.dev/` for Catalyst documentation 2. Web-search `site:developer.bigcommerce.com headless` for headless guide 3. Web-search `site:github.com bigcommerce catalyst` for Catalyst source and examples ## Headless Architecture ### What Headless Means for BigCommerce Decouple the frontend from BigCommerce: - BigCommerce serves as the **commerce backend** — catalog, orders, customers, payments - Your custom frontend handles **presentation** — React, Next.js, Vue, etc. - Communication via **APIs** — GraphQL Storefront API and REST API - Checkout via **Embedded Checkout** or **Custom Checkout** (Checkout API + Payments API) ### Why Headless - Full frontend control (design, UX, performance) - Use modern frameworks (Next.js, Remix, Astro) - Composable architecture — mix BigCommerce with CMS, search, etc. - Better performance with SSR/SSG/ISR - Multi-channel frontend from single BigCommerce backend ## Catalyst ### What It Is BigCommerce's official Next.js reference storefront: - Built on **Next.js 14+** with App Router - Uses **GraphQL Storefront API** for data - **Tailwind CSS** for styling - Full-featured: PLP, PDP, cart, checkout, customer account, search - Designed as a starting point to fork and customize ### Getting Started ```bash npx create-catalyst-storefront@latest my-store ``` Prompts for: - BigCommerce store URL - Channel ID - Storefront API token ### Project Structure ``` my-store/ ├── app/ # Next.js App Router pages │ ├── (default)/ # Default locale group │ │ ├── page.tsx # Homepage │ │ ├── product/ # Product pages │ │ ├── category/ # Category pages │ │ ├── cart/ # Cart page │ │ └── account/ # Customer account │ └── layout.tsx # Root layout ├── client/ # BigCommerce API client │ ├── queries/ # GraphQL queries │ └── mutations/ # GraphQL mutations ├── components/ # React components ├── lib/ # Utilities ├── public/ # Static assets ├── .env.local # Environment variables ├── next.config.js # Next.js config ├── tailwind.config.js # Tailwind config └── package.json ``` ### Key Environment Variables ``` BIGCOMMERCE_STORE_HASH=your_store_hash BIGCOMMERCE_ACCESS_TOKEN=your_access_token BIGCOMMERCE_CHANNEL_ID=1 BIGCOMMERCE_STOREFRONT_TOKEN=your_storefront_token BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN=your_token ``` ## Data Fetching Patterns ### Server Components (Recommended) Fetch data in Next.js Server Components using the GraphQL client: ```typescript // app/product/[slug]/page.tsx async function ProductPage({ params }: { params: { slug: string } }) { const product = await getProduct({ path: `/${params.slug}` }); return ; } ``` ### Client-Side Fetching For interactive features (cart, search-as-you-type): - Use React hooks with the GraphQL Storefront API - Storefront API token for unauthenticated requests - Customer impersonation token for personalized data ### Caching Strategy - **Static Generation (SSG)** — product and category pages at build time - **Incremental Static Regeneration (ISR)** — revalidate on interval or on-demand - **Server-Side Rendering (SSR)** — cart, checkout, account pages - **Client-Side** — search, cart updates, wishlist ## Checkout in Headless ### Embedded Checkout (Recommended) Embed BigCommerce's checkout in your headless site: 1. Create cart via API → get `redirect_urls.checkout_url` 2. Embed using `@bigcommerce/checkout-sdk` `embedCheckout()` 3. BigCommerce handles payment processing (no PCI scope) ### Custom Checkout Full API-driven checkout: 1. Cart API → Checkout API → Orders API → Payments API 2. Requires your own checkout UI 3. Payment processing via Payments API (PCI implications if handling raw card data) 4. Use tokenized payment methods to reduce PCI scope ## Authentication in Headless ### Customer Login - Use the Customer Login API (JWT-based SSO) to create sessions - Or implement custom auth and use Customer Impersonation Tokens for API access - Catalyst includes built-in authentication flows ### Session Management - BigCommerce sessions are cookie-based on the BigCommerce domain - For headless: use Customer Login API to set the cookie, then redirect to your domain - Or manage auth entirely on your side and use impersonation tokens ## Integration with Other Services ### Composable Commerce Stack BigCommerce + headless enables composable architecture: - **CMS**: Contentful, Sanity, Strapi for content - **Search**: Algolia, Bloomreach for product search - **Personalization**: Dynamic Yield, Nosto for recommendations - **PIM**: Akeneo, Salsify for product information - **OMS**: for order management ## Best Practices - Start with Catalyst — fork and customize rather than building from scratch - Use GraphQL Storefront API for frontend data fetching - Use REST API for server-side operations (order management, catalog sync) - Use Embedded Checkout to avoid PCI scope - Implement ISR for product/category pages — balance freshness and performance - Use customer impersonation tokens for personalized data - Handle webhook events for real-time data sync - Set up proper CORS configuration for Storefront API tokens - Use environment variables for all credentials Fetch the Catalyst documentation and BigCommerce headless guide for exact setup steps, GraphQL queries, and current best practices before implementing. --- Source attribution: OrcaQubits Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/bigcommerce-commerce/skills/bc-headless/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: OrcaQubits Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/bigcommerce-commerce/skills/bc-headless/SKILL.md Attribution basis: Source repository record Fields of work: Design, Development & Engineering, Marketing, Product Management Roles: Frontend Developer, Growth Marketer, Product Manager, Product Marketer, UX Designer Specialties: API, Frontend Tools: Bigcommerce, Graphql, Nextjs Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: d3df31d18b75b32470586e4a5aae2e35ada312a68e6714e79aa1d87c85b5001a