Getting started

OrbCart adds a transaction layer to the systems you already have. You bring the product data and storefront. It handles the Cart, Quote, Payment and Order.

1. Install the workspace

From the repository root:

pnpm install

Nordgrat, the example outdoor shop, is included. Start with it rather than wiring up a new storefront and payment provider at the same time.

2. Add your test credentials

Create .dev.vars at the repository root with these values from your Stripe test account. Replace every placeholder.

ROOT_SECRET=your-random-base64url-secret
STRIPE_SECRET_KEY=sk_test_your_stripe_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_key
STRIPE_WEBHOOK_SECRET=whsec_your_listener_secret

Generate ROOT_SECRET locally:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'

For local payment webhooks, run the Stripe CLI in another terminal:

stripe listen --latest --all-snapshot --forward-to localhost:8787/webhooks/stripe

Copy the listener's signing secret into STRIPE_WEBHOOK_SECRET. Keep the listener running. Without the Stripe CLI, follow Stripe's local setup first.

The demo also needs its own sign-in secret. Generate another random value with the command above and put it in apps/demo/.dev.vars:

BETTER_AUTH_SECRET=another-random-base64url-secret

Both files are ignored by Git. Never put their contents in browser code, URLs or logs.

3. Start the shop

Run each command in its own terminal, from the repository root:

pnpm --filter @orbcart/example-nordgrat systems

pnpm --filter @orbcart/demo commerce

Wait until OrbCart is ready, then start the storefront:

pnpm --filter @orbcart/demo dev

Open localhost:5173/en. Add a backpack, open the Cart, and use fictional details at checkout. Behind the scenes shows the actual SDK calls and the server's answers.

The commerce command writes local OrbCart keys into apps/demo/.dev.vars, keeping your sign-in secret. These are separate from your Stripe keys.

Where to start reading

Ready to write code? Create your first Cart →