Better Store Documentation

Better Store is a TypeScript toolkit for building online storefronts on top of the Better Store commerce platform.

Use these docs when you want to show products, manage a cart, create checkout sessions, and embed checkout in a React or Next.js storefront.

What This Gives You

Tool	Use it for
`@betterstore/sdk`	Calling the Better Store API from server-side code.
`@betterstore/react`	Building cart and checkout UI in React.
`@betterstore/helpers`	Formatting prices, currencies, and other commerce values.
`examples/nextjs-basic`	Learning from a complete Next.js storefront example.

The Better Store platform runs the backend commerce system: products, customers, checkout, payments, shipping, discounts, tax, and merchant operations. The public toolkit connects custom storefronts to that platform.

What You Can Build

A custom storefront for a Better Store merchant.
A product listing page backed by Better Store data.
A cart experience in React.
A checkout flow embedded inside your app.
A market-aware storefront that resolves country, currency, availability, and checkout context.
A Next.js commerce site using the included example.

How It Works

Customer storefront
  -> server code uses @betterstore/sdk
  -> Better Store API creates products, customers, and checkout sessions
  -> React UI uses @betterstore/react
  -> CheckoutEmbed completes checkout for the customer

The important security rule is simple:

BETTERSTORE_SECRET stays on the server.
checkoutSecret can be passed to CheckoutEmbed for one checkout session.

Packages

Install only what your app needs:

bun add @betterstore/sdk
bun add @betterstore/react
bun add @betterstore/helpers

Package	Environment	Notes
`@betterstore/sdk`	Server-first	Use with your private `BETTERSTORE_SECRET`.
`@betterstore/react`	Browser/React	Includes `useCart` and `CheckoutEmbed`; requires `react` and `react-dom`.
`@betterstore/helpers`	Server or browser	Small utilities such as price formatting.

Documentation Map

Page	What it covers
Getting Started	Install packages, create an SDK client, and checkout.
Next.js Basic Example	Run and understand the included Next.js example.
API Authentication	Authenticate API requests safely.

SDK Areas

Area	What it is for
`products`	Product data.
`collections`	Product collections.
`customers`	Customer data and actions.
`auth`	Customer authentication.
`checkout`	Checkout sessions.
`markets`	Buyer country to market resolution.
`utils`	Utility API endpoints.

Security Rules

Never expose BETTERSTORE_SECRET in browser code.
Use createBetterStore only on the server.
Only send checkout-specific checkoutSecret values to the browser.
Put real local credentials in .env.local.
Keep .env.example files as placeholders only.
Do not commit generated local files like packages/react/src/dev/.env.development.

Before making the public toolkit repo public or publishing a release, run a secret scan and rotate any secret that was ever committed.

On this page