Quickstart

You need Node 22. Node 18 fails with misleading “command not found” errors from the build tooling, so run nvm use first; the version is pinned in .nvmrc.

git clone https://github.com/binx/beluga-v2.git my-store
cd my-store
nvm use
npm install
npm run setup       # generates secrets, checks your Stripe key, makes your admin account
npm run dev:all     # storefront on :5173, API on :4000

npm run setup asks a handful of questions and writes .env once. It never touches that file again, so re-running it will not repair a value you changed by hand. Give it a Stripe test secret key if you have one; it validates the key against Stripe before storing it and says plainly whether you handed it a live one. Say yes to seeding the demo catalogue.

Then open http://localhost:5173. The storefront shows the demo products, and http://localhost:5173/admin signs in with the account setup created.

Prefer a browser?

Skip setup and run npm run dev:all on its own. The server starts unconfigured on purpose, and http://localhost:5173/setup walks the same three steps in a wizard.

No terminal at all (containers, CI)

SESSION_SECRET=$(openssl rand -base64 32) \
ADMIN_EMAIL=you@example.com ADMIN_PASSWORD='a long passphrase' \
npm run db:seed

Taking a test payment

A product must be published before it can be bought, and only Stripe’s webhook marks an order paid. Locally that means forwarding webhooks with the Stripe CLI:

stripe listen --forward-to localhost:4000/api/webhooks/stripe

Put the whsec_… it prints into .env as STRIPE_WEBHOOK_SECRET, restart the API, publish a product from the admin, and pay with card 4242 4242 4242 4242. The restart is the step everyone skips.

What you have now

A store that browses, carts and sells against a SQLite file under data/, with uploaded images under public/assets/. Neither needs a database server. To make it yours, read Architecture once, then Build your first store.