Storefront Development

Build fast, modern storefronts using the Hanzo Commerce TypeScript SDK. The SDK handles all communication with the Commerce API, letting you focus on the shopping experience.

Getting Started

npm install @hanzo/commerce

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({
  apiKey: process.env.HANZO_API_KEY!,
  environment: 'production',
})

Storefront Architecture

┌─────────────────────────────────┐
│       Next.js / React App       │
│  ┌───────────┐ ┌─────────────┐  │
│  │  Product  │ │    Cart     │  │
│  │  Pages    │ │   Drawer    │  │
│  ├───────────┤ ├─────────────┤  │
│  │  Checkout │ │   Account   │  │
│  │  Flow     │ │   Pages    │  │
│  └─────┬─────┘ └──────┬──────┘  │
│        │               │        │
│  ┌─────┴───────────────┴──────┐ │
│  │     @hanzo/commerce SDK    │ │
│  └────────────┬───────────────┘ │
└───────────────┼─────────────────┘
                │ HTTPS
                ▼
        Hanzo Commerce API

Key Flows

Package

Products

Product listing, detail pages, categories, and search

ShoppingBag

Cart

Cart creation, item management, and coupon application

CreditCard

Checkout

Address, shipping selection, payment, and order completion

User

Customers

Registration, login, profile management, and order history

Globe

Regions

Multi-region and multi-currency support

Recommended Stack

Layer	Technology
Framework	Next.js 14+ (App Router)
UI	@hanzo/ui components
State	React Context or Zustand
SDK	@hanzo/commerce
Styling	Tailwind CSS
Deployment	Vercel

Quick Example: Product Page

import { commerce } from '@/lib/commerce'

export default async function ProductPage({ params }: { params: { slug: string } }) {
  const product = await commerce.products.getBySlug(params.slug)

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{(product.price / 100).toFixed(2)} {product.currency}</p>
      <p>{product.description}</p>
      <AddToCartButton variantId={product.variants[0].id} />
    </div>
  )
}

For a complete storefront template, see the Next.js Storefront recipe.