commerce-js-integration（商务 js 集成）

Commerce.js Integration

Overview

Commerce.js (Chec) is a headless commerce platform offering a JavaScript SDK that wraps its REST API for managing products, carts, checkouts, and orders. It is designed for developers who want to add commerce functionality to any website or JavaScript framework without the complexity of a full e-commerce platform. The SDK handles product fetching, cart lifecycle, checkout token creation, and order capture in a straightforward, promise-based API.

When to Use This Skill

• When you want to add e-commerce to a static site or simple React/Vue/Svelte project quickly
• When you don't need a complex backend and want a managed commerce API without server-side code
• When building a portfolio project, MVP, or proof-of-concept headless store
• When your catalog is small (under 1,000 products) and you don't need custom fulfillment logic
• When you want a simple SDK without managing a full Shopify or commercetools environment

Prerequisites & Platform Notes

This skill is written for custom/headless storefronts (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

Shopify: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services. WooCommerce: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress. Magento: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

You'll need:

• Node.js 18+ (or adapt to your backend language)
• Stripe account and API keys
• An email sending service (SendGrid, AWS SES, or Postmark)

Core Instructions

1. Install the SDK and initialize the client npm install @chec/commerce.js import Commerce from '@chec/commerce.js'; // Public key is safe to expose in the browser const commerce = new Commerce(process.env.NEXT_PUBLIC_CHEC_PUBLIC_KEY, true); // true = debug mode Get your public API key from the Chec Dashboard under Developer → API keys.
2. Fetch and display products // Fetch all products const {data: products} = await commerce.products.list({limit: 20, page: 1, sort_by: 'created', sort_direction: 'desc',}); // Fetch a single product by permalink (slug) const product = await commerce.products.retrieve('my-product-slug', {type: 'permalink'}); // Products include structured data console.log({id: product.id, name: product.name, price: product.price.formatted_with_symbol, // "$29.99" description: product.description, // HTML string from Chec CMS image: product.image?.url, variants: product.variants, // Size, color options}); React component example: import {useEffect, useState} from 'react'; import Commerce from '@chec/commerce.js'; const commerce = new Commerce(process.env.NEXT_PUBLIC_CHEC_PUBLIC_KEY!); export function ProductGrid() {const [products, setProducts] = useState<any[]>([]); const [loading, setLoading] = useState(true); useEffect(() => {commerce.products.list().then(({data}) => setProducts(data)).finally(() => setLoading(false));}, []); if (loading) return <div>Loading...</div>; return (<div className="grid grid-cols-3 gap-6"> {products.map(product => (<div key={product.id} className="border rounded-lg p-4"> <img src={product.image?.url} alt={product.name} className="w-full h-48 object-cover" /> <h2 className="mt-2 font-semibold">{product.name}</h2> <p className="text-gray-600">{product.price.formatted_with_symbol}</p> <AddToCartButton productId={product.id} /> </div>))} </div>);}
3. Manage the cart Commerce.js stores the cart ID in localStorage automatically: // Get or create the current cart const cart = await commerce.cart.retrieve(); // Add a product to the cart const updatedCart = await commerce.cart.add(productId, quantity, {// Optional: specify variant selections variantId: 'variant_id_here', optionId: 'option_id_here',}); // Update line item quantity await commerce.cart.update(lineItemId, {quantity: 3}); // Remove a line item await commerce.cart.remove(lineItemId); // Empty the cart await commerce.cart.empty(); // Refresh the cart const refreshedCart = await commerce.cart.refresh(); Cart state management with React Context: // context/cart-context.tsx import {createContext, useContext, useState, useEffect} from 'react'; import Commerce from '@chec/commerce.js'; const commerce = new Commerce(process.env.NEXT_PUBLIC_CHEC_PUBLIC_KEY!); const CartContext = createContext<any>(null); export function CartProvider({children}: {children: React.ReactNode}) {const [cart, setCart] = useState<any>(null); useEffect(() => {commerce.cart.retrieve().then(setCart);}, []); const addToCart = async (productId: string, quantity = 1) => {const {cart: updated} = await commerce.cart.add(productId, quantity); setCart(updated);}; const removeFromCart = async (lineItemId: string) => {const {cart: updated} = await commerce.cart.remove(lineItemId); setCart(updated);}; return (<CartContext.Provider value={{cart, addToCart, removeFromCart}}> {children} </CartContext.Provider>);} export const useCart = () => useContext(CartContext);
4. Generate a checkout token and capture the order ` // Step 1: Generate a checkout token from the cart const checkoutToken = await commerce.checkout.generateToken(cart.id, {type: 'cart'}); // Step 2: Get live checkout information (shipping options, taxes) const checkoutData = await commerce.checkout.getLive(checkoutToken.id); // Step 3: Capture the order const order = await commerce.checkout.capture(checkoutToken.id, {customer: {firstname: 'Jane', lastname: 'Doe', email: 'jane@example.com',}, shipping: {name: 'Jane Doe', street: '123 Main Street', town_city: 'San Francisco', county_state: 'US-CA', postal_zip_code: '94103', country: 'US',}, fulfillment: {shipping_method: checkoutData.shipping.available_options[0].id,}, payment: {gateway: 'stripe', stripe: {payment_method_id: stripePaymentMethodId, // from Stripe.js},},}); console.log(Order #${order.customer_reference} placed!); // Clear the cart after successful order await commerce.cart.refresh(); `
5. Handle product variants ` const product = await commerce.products.retrieve(productId); // Variants are organized as variant groups (e.g., "Size") with options (e.g., "S", "M", "L") product.variants.forEach(variantGroup => {console.log(Variant group: ${variantGroup.name}); variantGroup.options.forEach(option => {console.log( - ${option.name}: +${option.price.formatted_with_symbol});});}); // When adding to cart, provide the full variant selection const selections = {[sizeVariantGroupId]: selectedSizeOptionId, [colorVariantGroupId]: selectedColorOptionId,}; await commerce.cart.add(product.id, 1, selections); `
6. List and display orders // Requires a customer JWT (obtained via commerce.customer.login) const customerToken = await commerce.customer.login(email, password); const {data: orders} = await commerce.orders.getAllForCustomer({customer_token: customerToken.token,}); orders.forEach(order => {console.log({reference: order.customer_reference, status: order.status, total: order.order_value.formatted_with_symbol, items: order.order.line_items.map(item => item.product_name),});});

Examples

Complete Next.js product page

// app/products/[permalink]/page.tsx
import Commerce from '@chec/commerce.js';
import DOMPurify from 'isomorphic-dompurify';

// Server-side: use secret key to fetch product at build time
const commerce = new Commerce(process.env.CHEC_SECRET_KEY!);

export async function generateStaticParams() {
  const {data: products} = await commerce.products.list({limit: 200});
  return products.map((p: any) => ({permalink: p.permalink}));
}

export default async function ProductPage({params}: {params: {permalink: string}}) {
  const product = await commerce.products.retrieve(params.permalink, {type: 'permalink'});
  // Sanitize HTML from Chec CMS before rendering
  const safeDescription = DOMPurify.sanitize(product.description ?? '');

  return (
    <main>
      <img src={product.image?.url} alt={product.name} />
      <h1>{product.name}</h1>
      {/* Sanitized HTML rendered safely */}
      <div dangerouslySetInnerHTML={{__html: safeDescription}} />
      <p className="text-xl font-bold">{product.price.formatted_with_symbol}</p>
    </main>
  );
}

Cart item count badge

export function CartBadge() {
  const {cart} = useCart();
  const totalItems = cart?.total_unique_items ?? 0;

  return (
    <button className="relative">
      <ShoppingCartIcon />
      {totalItems > 0 && (
        <span className="absolute -top-2 -right-2 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
          {totalItems}
        </span>
      )}
    </button>
  );
}

Best Practices

• Use the public key on the client, secret key on the server — the public key can only read products and manage carts; the secret key can also manage orders and is not safe to expose in browser code
• Initialize the Commerce client once — create a single instance in a module-level constant and import it; avoid creating a new instance on every render
• Handle webhook events for order automation — configure Chec webhooks in the dashboard to POST to your server when orders are placed, updated, or refunded
• Use checkout tokens, not cart IDs, for checkout — generateToken creates a time-limited, checkout-specific token; always pass this token to capture, never the raw cart ID
• Refresh the cart after order capture — calling commerce.cart.refresh() after a successful order creates a fresh empty cart; the old cart ID is invalidated
• Sanitize product description HTML before rendering — product descriptions are HTML from the Chec CMS; always run them through DOMPurify (isomorphic-dompurify works in both Node.js and browser) before rendering
• Implement error handling for checkout capture — wrap commerce.checkout.capture in try/catch and map commerce.error codes to user-friendly messages

Common Pitfalls

Related Skills

• @jamstack-storefront
• @shopify-hydrogen
• @secure-checkout
• @webhook-architecture