Quickstart
Get the storefront running locally in under five minutes.
Nordcom Commerce is a multi-tenant headless e-commerce platform. A single Next.js deployment serves an arbitrary number of shops resolved by hostname.
Prerequisites
- Node.js (version pinned in
.nvmrc) - pnpm
The data layer is Convex — pnpm convex:dev provisions an
anonymous local backend, so there is no database server to install.
Run pnpm dev:storefront if you only need the storefront — it boots a single app
and skips the admin and landing builds. Use pnpm dev to start all three in parallel.
Install
pnpm install
cp .env.example .env # Convex vars default to the local backend on :3210
pnpm build:packages # apps import from each package's dist/, not source
pnpm dev # boots + seeds the local Convex backend, then all apps| App | URL |
|---|---|
| Storefront | https://storefront.localhost |
| Admin | https://admin.localhost |
| Landing | https://landing.localhost |
| Docs | https://docs.localhost |
pnpm dev is local-first: it runs pnpm convex:local, which boots a persistent
anonymous Convex backend on :3210 (in .convex-local/), pushes the schema, and
applies the advanced canonical seed. Manage it with pnpm convex:local,
pnpm convex:local:reset, and pnpm convex:local:stop. Point CONVEX_URL /
NEXT_PUBLIC_CONVEX_URL / CONVEX_SERVER_SECRET at a hosted deployment to use the
cloud instead.
Seed a tenant
The storefront resolves every request by hostname. Without a matching Shop row in
the Convex shops table, every request redirects to /status/unknown-shop/. In
development, unknown hosts fall back to nordcom-demo-shop.com automatically so you
can boot without seeding.
To seed the canonical demo tenant (the same fixtures the e2e suites use), run the
seedCanonical helper from @nordcom/commerce-test-convex against your deployment.
Real tenants are created through the admin app, which writes the shops row via the
db/shop_write:upsertShop mutation.
No redeploy required. Middleware picks up the new row on the next request.
Quality gates
Before pushing, run:
pnpm lint # Biome lint
pnpm typecheck # TypeScript across all packages and apps
pnpm test # Vitest unit tests (convex-test in-memory — no backend needed)CI runs the same gates on every PR.