Ecommerce Boilerplate Documentation

An open-source, self-hostable ecommerce starter on Next.js 16, React 19, TypeScript, Tailwind 4, and your own Postgres.

An open-source ecommerce starter you can clone, rebrand, and ship. It carries a storefront, an admin dashboard, a checkout, and a commerce layer that is not welded to any one database.

It runs before you configure anything.

Terminal

git clone <this-repo> && cd ecommerce-boilerplate
npm install
npm run dev

That serves a populated store on localhost:3000: 18 demo products, category filters, search, product pages, a working cart, and a local checkout. No account, no credentials, no database. When you are ready for real data, point it at SQLite (one file, nothing to install), your own Postgres, Supabase, or Firebase — the same app keeps running.

Where to go next

Quick start

Clone, connect a backend, seed the catalog, grant yourself admin.

Choose a backend

Demo, SQLite, Postgres, Supabase, or Firebase behind one interface.

Make it yours

Name, contact, navigation, categories, currencies, locales, theme.

Run the store

Products, orders, quotes, discounts, media, customers.

Storefront features

Catalog, cart, checkout, inventory, variants, SEO.

Store API

Read-only catalog endpoints with cursor pagination.

What ships in the box

Shopper side. Landing page, catalog with category filters and search, product pages with variants and related products, guest and signed-in carts, Stripe checkout when configured, and a quote-request path for stores that sell on price-on-request. Language, currency, and brand theme are switchable from the header and resolved server-side, so the first paint is already correct.

Merchant side. An admin dashboard at /admin: product CRUD, featured curation, order fulfillment, the quote pipeline, discount codes, a media library, customers, and an append-only activity log. Access is role-based and enforced by the shipped firestore.rules, not by hiding the UI.

Developer side. One typed commerce interface (src/lib/commerce) with adapters for the demo fixture, Postgres/Prisma (which also drives SQLite), Supabase, and Firebase; typed lifecycle events to hook into instead of forking; a read-only public Store API; SEO pack; and a Vitest suite.

Every heavy dependency is optional and env-gated. Stripe, Resend email, and the database adapters stay off until you set their variables, so a first deploy needs nothing you have not decided to add. The one thing every configuration shares is Firebase Auth as the identity provider — a Postgres store still needs a Firebase project for sign-in.

Rebrandable in an afternoon

Names, contact details, navigation, product categories, currencies, locales, and theme presets live in one file, src/config/site.ts. Brand colors are four CSS variables.

src/config/site.ts

export const siteConfig = {
  name: "Kestrel Supply",
  tagline: "Technology worth keeping",
  url: "https://ecommerce-boilerplate.com",
  currency: { code: "USD", locale: "en-US" } satisfies CurrencyConfig,
  // contact, mainNav, locales, currencies, theme presets…
} as const;

Who these docs are for

Building on the boilerplate (cloning, configuring, theming, swapping backends, calling the API): start at Quick start, then Site config.

Running a store (adding products, working orders and quotes, managing discounts and media): start at the Admin overview.

Tech stack

Next.js 16 (App Router) · React 19 · TypeScript 6 · Tailwind CSS 4 · shadcn/ui on Radix · Zod 4 · Vitest 4 · framer-motion. Data layer: the bundled demo fixture, SQLite or Postgres via Prisma 7, Supabase, or Firestore. Identity: Firebase Auth. Optional: Stripe for payments, Resend for email. Versions on the tech stack page are checked against package.json by a test.

Where this is headed: a self-hostable commerce platform with the developer experience of Medusa and the merchant experience of Shopify. ROADMAP.md in the repo tracks what is done and what is open.