shopstart

shopstart is a clone-and-build e-commerce site template. It's not a store — it's a starting point: a working storefront, admin dashboard, and API with the boring parts (auth, cart, checkout, orders, inventory) already correct, so you can rename it and build your actual store on top instead of starting from a blank repo.

Use this as a GitHub template ("Use this template" button) or git clone it directly.

Tech stack

• API — NestJS + Prisma + PostgreSQL
• Storefront (apps/web) — TanStack Start (SSR, for SEO)
• Admin dashboard (apps/admin) — TanStack Router (client-only SPA)
• Runtime — Bun
• Monorepo — Turborepo + Bun workspaces

See docs/adr/ for why these were chosen over the alternatives, and CONTEXT.md for the domain glossary (Cart vs Order, what a Review requires, how Order status transitions work, etc).

Folder structure

shopstart/
├── apps/
│   ├── api/            # NestJS REST API (Prisma + PostgreSQL)
│   ├── web/            # TanStack Start storefront (SSR)
│   │   └── design.md   # Locked storefront design system — read before UI changes
│   └── admin/          # TanStack Router admin dashboard (SPA)
├── packages/
│   └── types/          # Shared Zod schemas + TS types, used by all three apps
├── docs/adr/           # Architecture decision records
├── CONTEXT.md          # Domain glossary
├── ROADMAP.md          # What's solid, what's thin, what's deliberately not planned
└── CONTRIBUTING.md     # Development workflow, code style, testing conventions

Getting started

Prerequisites

• Bun >= 1.3
• Docker (for local PostgreSQL) — or point DATABASE_URL at any Postgres instance you already have

1. Install dependencies

bun install

2. Start PostgreSQL

docker compose up -d

3. Configure environment variables

Copy the example env files and fill in real secrets for JWT_ACCESS_SECRET / JWT_REFRESH_SECRET (openssl rand -base64 32):

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/admin/.env.example apps/admin/.env

4. Run migrations and seed demo data

bun run db:migrate
bun run seed

This creates a demo admin (admin@shopstart.dev / shopstart-admin) and a demo customer (customer@shopstart.dev / shopstart-customer), plus a handful of categories and products.

5. Start everything

bun run dev

• API: http://localhost:4000 (Swagger docs at /docs)
• Storefront: http://localhost:3000
• Admin: http://localhost:3001

What's included vs. what you build

shopstart ships a complete domain model — User, Address, Category, Product, Review, Cart, Order, Wishlist — with real business rules (stock decrements transactionally at checkout, order prices are snapshotted so they never change retroactively, reviews require a verified purchase). See CONTEXT.md for the full glossary.

It deliberately leaves some things as extension points rather than guessing at your specific store's needs:

Area	What shopstart gives you	What you add
Payments	A PaymentProvider interface + a stub that auto-succeeds for local dev	A real gateway integration (Stripe, etc.) — see docs/adr/0003
Product images	An imageUrl string field	Wherever you want to host images — no upload pipeline is built in
Coupons / discounts	Not modeled	Your own pricing rules, if you need them
Shipping methods	Not modeled	Flat-rate, carrier-calculated, etc., per your store

Testing

• apps/api — Jest unit tests (bun run --cwd apps/api test), one *.spec.ts per service, PrismaService mocked at the DB boundary.
• apps/web, apps/admin, packages/* — Vitest (bun run --cwd apps/web test)
• bun run test runs all of the above via Turborepo

API e2e tests

apps/api/test/*.e2e-spec.ts boot the real Nest app (real guards, real cookies, real Zod validation) against a real Postgres database — this is what proves the checkout stock guard actually prevents overselling under concurrent requests, which a mocked-Prisma unit test structurally cannot prove.

One-time setup (assumes docker-compose up -d is already running the dev Postgres):

docker compose exec postgres psql -U shopstart -d shopstart -c "CREATE DATABASE shopstart_test"
cp apps/api/.env.test.example apps/api/.env.test
cd apps/api && DATABASE_URL="postgresql://shopstart:shopstart@localhost:5432/shopstart_test" bunx prisma migrate deploy

Then: bun run --cwd apps/api test:e2e. e2e tests run with maxWorkers: 1 (see apps/api/test/jest-e2e.json) since every spec file truncates and reuses the same shared database — running spec files in parallel would race.

See docs/adr/0006-testing-strategy.md for why the suite is split into unit/e2e/component layers rather than one style throughout.

Contributing

See CONTRIBUTING.md for the development workflow, code style, and testing conventions. ROADMAP.md lists what's solid, what's thin, and what's deliberately out of scope — a good place to check before starting new work.

License

MIT — see LICENSE.