Create new Catalyst storefront

<overview> Headless commerce decouples thefrontend presentation layer from BigCommerce'sbackend . Use BigCommerce as the commerce engine while building custom storefronts with frameworks likeNext.js , React, or Vue. BigCommerce provides Catalyst andNext.js Commerce as official headless solutions. </overview > <architecture> <headlessconcept > **Traditional (coupled):** - The Stencil theme renders webfrontend - Backend and frontfrontend s are tightly integrated - Limited to BigCommerce’s rendering **Headless (decoupled):** - Custom frontfrontend s (React, Vue, etc.) - APIs connect to BigCommerce’backend - Full control over the user experience - Multiple frontends possible (web, mobile, kiosk) </headlessconcept > <bigcommercerole > BigCommerce handles: - Product catalog management - Inventory tracking - Order processing - Customer management - Payment processing - Tax calculation - Shipping integrations Yourfrontend handles: - User interface - User experience - Performance optimization -SEO implementation </bigcommercerole > </architecture > <official_solutions > <catalyst> BigCommerce Catalyst - The composable headless framework Built with: -Next.js 14 (App Router) - React Server Components - GraphQL StorefrontAPI - TypeScript ``bash # Create new Catalyst storefront npx create-catalyst-storefront@latest my-store Features: - Fully functional storefront out of the box - Customizable UI component library - Optimized for performance (SSR, RSC) - SEO and accessibility built-in - Multi-region support Best for: New headless projects, rapid development </catalyst> <nextjs_commerce> **Next.js Commerce** - Reference implementation GitHub: https://github.com/bigcommerce/nextjs-commerce Integration with BigCommerce via: - GraphQL Storefront API - storefront-data-hooks (SWR-based) Features: - Vercel-optimized deployment - Image optimization - Analytics integration - Multi-storefront support Best for: Learning headless patterns, Vercel deployment </nextjs_commerce> </official_solutions> <api_strategy> <graphql_for_storefront> Use GraphQL Storefront API for: - Product catalog queries - Cart operations - Checkout initiation - Customer data (with impersonation token) - Site content graphql query GetStorefrontData { site { products(first: 10) { edges { node { entityId name prices { price { value } } } } } categoryTree { name path children { name path } } } } </graphql_for_storefront> <rest_for_management> Use REST APIs (server-side) for: - Creating/updating products - Order management - Customer account creation - Inventory updates - Webhook subscriptions Keep REST calls server-side to protect credentials. </rest_for_management> <hybrid_approach> Typical headless architecture: [Browser] → [Your Frontend Server] → [BigCommerce APIs] Frontend handles: - GraphQL Storefront (can be client-side with token) - SSR rendering Backend proxy handles: - REST Management APIs - Sensitive operations - Webhook receiving </hybrid_approach> </api_strategy> <cart_checkout> <cart_with_graphql> graphql mutation CreateCart($input: CreateCartInput!) { cart { createCart(input: $input) { cart { entityId lineItems { physicalItems { entityId name quantity } } } } } } </cart_with_graphql> <checkout_options> Three approaches for checkout: **1. Redirect Checkout (simplest)** graphql query GetCheckoutUrl($cartId: String!) { site { cart(entityId: $cartId) { redirectUrls { redirectedCheckoutUrl } } } } User redirects to BigCommerce-hosted checkout. **2. Embedded Checkout** javascript // Embed BigCommerce checkout in iframe const checkoutUrl = cart.redirectUrls.embeddedCheckoutUrl; <iframe src={checkoutUrl} /> `` Check out on your site; BigCommerce handles payment. 3. Custom Checkout (advanced) Build your own checkout UI using: - CheckoutAPI for state management - PaymentsAPI for processing - Requires PCI compliance considerations </checkoutoptions > </cartcheckout > <a