bermooda

Beta: bermooda is currently in active beta development. APIs, schemas, and CLI behavior may change before a stable 1.0 release.

Own your ecommerce stack. bermooda is an open-source ecommerce platform that runs as a single deployable app: themed storefront, merchant admin, and REST API—together.

Clone it, scaffold a shop in minutes, and ship real catalog, cart, checkout, orders, and staff tools without bolting together a half-dozen SaaS products. Domain logic lives in one place (app/core/*), so you can read, change, and extend the engine like any other Node app.

If you want a full shop you can fork, understand, and grow—welcome.

Why engineers try it

• One service, three surfaces — storefront, admin, and public/admin REST APIs in a single React Router app
• Real commerce primitives — catalog, cart, checkout, payments, shipping, customers, discounts, inventory, and more under app/core/*
• Themes & plugins — swap storefront UI under app/themes/*; extend behavior with hook-based plugins under app/plugins/*
• Local-first — SQLite for development, PostgreSQL when you need it; no Docker or external DB required to start
• CLI-first setup — bermooda install scaffolds deps, env, database, admin user, and store name for you

Stack

| Layer | Choice | | ------------- | ---------------------------------------------------------------------------------------- | | Runtime | Node.js ≥ 24 | | App framework | React Router (SSR, loaders, actions) | | UI | React, Tailwind CSS | | Build | Vite | | Data | Prisma · SQLite (local) · PostgreSQL (production-ready) | | Auth | better-auth (separate admin/staff and customer sessions) | | Payments | Stripe | | Email | Resend (+ React Email templates) | | Deploy | Plain Node / Docker | | Quality | Vitest, oxlint, oxfmt |

Quick start (recommended)

Scaffold a shop with the global CLI:

npm i -g @bermooda/cli@latest

bermooda install --local --dir ./my-shop -y \
  --admin-email [email protected] \
  --admin-password 'TestPass123!' \
  --store-name 'Demo Shop'

cd my-shop
bermooda dev

Open http://localhost:3000. Admin is typically at /admin.

Install the CLI

npm i -g @bermooda/cli@latest

Requires Node.js ≥ 24. After install, the bermooda binary is available globally.

CLI commands (overview)

| Command | What it does | | -------------------------------------- | -------------------------------------------------------------------- | | bermooda install [--local\|--server] | Download app, install deps, configure env & DB, create admin + store | | bermooda dev | Start the dev server (no 1Password wrapper) | | bermooda start | Run production server (builds if needed) | | bermooda update | Update the shop to the latest app version | | bermooda plugin … | Add / update / remove / list plugins | | bermooda theme … | Add / update / remove / list themes | | bermooda version | Show CLI and shop versions | | bermooda upgrade | Upgrade the CLI itself | | bermooda help [command] | Built-in help |

Full command reference, flags, and design notes: see the @bermooda/cli README and DESIGN.md. In-repo product checklist: docs/cli-specs.md.

Offline install from a local checkout of this repo:

bermooda install --local --source /path/to/bermooda --dir ./my-shop -y \
  --admin-email [email protected] \
  --admin-password 'TestPass123!' \
  --store-name 'Demo Shop'

Working from this repository

Useful if you are contributing to the platform itself:

npm install
npm run setup          # .env + config + prisma generate/migrate + default theme
npm run seed           # optional demo catalog + admin

Development

# Default local script (wraps env with 1Password CLI if you use it):
npm run dev

# Plain env file (no 1Password):
npx react-router dev --port 3000 --host
# or, with the CLI installed:
bermooda dev

App: http://localhost:3000

Common scripts

| Task | Command | | ---------------------- | ----------------------------------------- | | Full local setup | npm run setup | | Seed demo data | npm run seed | | Install default theme | npm run extensions:install | | Install extension deps | npm run extensions:install-deps | | Tests | npm run test | | Lint | npm run lint | | Format | npm run fmt | | Production build | npm run build | | New migration | npm run prisma:migrate -- --name <name> |

Reset local SQLite: delete prisma/dev.db and re-run npm run setup.

Architecture (at a glance)

app/
  core/       # Domain workflows (catalog, cart, orders, payments, …)
  libs/       # Infrastructure (auth, Prisma, queue, alerting, SDKs)
  routes/     # Storefront, admin, API, webhooks, auth
  themes/     # Storefront themes (active theme renders the shop)
  plugins/    # Hook-based extensions (blocks, admin pages, providers)
  components/ # Shared admin / auth / UI primitives

• Routes stay thin: loaders/actions call app/core/*.
• Themes receive data via props/loaders; they do not import server core modules.
• Plugins register hooks, providers, and optional admin/storefront UI.

Deeper reading:

• docs/themes.md — storefront themes
• docs/plugins.md — plugin system
• docs/api.md — public & admin REST API
• docs/auth.md — dual admin / customer auth
• docs/testing.md — Vitest setup

Configuration

Copy .env.example to .env (or run npm run setup, which creates it when missing). Placeholder values are enough to boot the app; wire real keys when you need payments, email, OAuth, or object storage.

Notable variables:

| Variable | Purpose | | ------------------------------------------- | --------------------------------------------------------------- | | DATABASE_URL | SQLite (file:./prisma/dev.db) or PostgreSQL connection string | | BETTER_AUTH_SECRET | Auth secret; also encrypts plugin password settings at rest | | STRIPE_* | Payments | | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | Optional Google OAuth | | STORAGE_* | S3-compatible object storage (AWS S3, MinIO, R2, etc.) |

Google OAuth (optional)

1. Create a project in the Google Cloud Console
2. Create OAuth client credentials (Web application)
3. Authorized redirect URIs:
   • Development: http://localhost:3000/auth/callback/google
   • Production: https://your-domain/auth/callback/google
4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env

Production

Build

npm run build
npm start   # or: bermooda start

Build output:

build/
  client/   # Static assets
  server/   # Server bundle

Docker

docker build -t bermooda .
docker run -p 3000:3000 bermooda

# With env file and SQLite path (example):
docker run -p 3000:3000 --env-file .env \
  -e DATABASE_URL=file:/data/sqlite.db bermooda

See docs/storage.md and docs/postgres.md when you move beyond local SQLite.

Contributing

Issues and PRs that improve the commerce core, themes, plugins, docs, or DX are welcome. Prefer small, focused changes that match patterns in nearby files. Project conventions live in AGENTS.md / Claude.md.

npm run test
npm run lint