Tech Stack

A self-hostable ecommerce starter on Next.js 16 with the App Router and React 19. It runs with no configuration at all against a bundled demo catalog; for real data the recommended path is PostgreSQL through Prisma — or SQLite, which is the same adapter over a file — with Supabase and Firebase as alternatives behind the same interface.

What is required, and what is not

Nothing on the default path needs an account. The store boots on the bundled fixture catalog; each heavier capability turns on only when you set its variables.

Core stack

The load-bearing dependencies every install uses.

Why the App Router

Server components fetch the catalog and resolve locale, currency, and theme before the first paint, so prices and language are right in the initial HTML instead of being corrected after hydration. Product and category pages carry their own generateMetadata and JSON-LD. Route handlers under src/app/api/* serve the public Store API, the checkout endpoint, and the commerce RPC bridge.

Data layer

The commerce layer (src/lib/commerce) defines one typed interface, CommerceServices, and every adapter satisfies it. Switching is an env var, not a fork; see choosing a backend.

PostgreSQL via Prisma (recommended), and SQLite

Your own database, standard SQL, no vendor lock-in. The adapter is server-side only: the browser reaches it through the /api/commerce RPC route, so the connection string never leaves the server.

SQLite is the same adapter. One CommerceServices implementation over one set of models; only three statements differ by engine, all documented on the SQLite page. It is the shortest path to real writes while developing — a file, nothing to install — and moving to Postgres later is two env vars.

# .env.local — Postgres
DATABASE_URL="postgresql://user:password@localhost:5432/store"
COMMERCE_BACKEND=postgres
NEXT_PUBLIC_COMMERCE_BACKEND=postgres

npm run prisma:generate
npm run prisma:push

# .env.local — SQLite (COMMERCE_BACKEND also picks the schema file, so pass it)
DATABASE_URL="file:./dev.db"
COMMERCE_BACKEND=sqlite
NEXT_PUBLIC_COMMERCE_BACKEND=sqlite

COMMERCE_BACKEND=sqlite npm run prisma:generate
COMMERCE_BACKEND=sqlite npm run prisma:push

Setup in full: Postgres and Prisma, SQLite.

Supabase

Hosted Postgres with row-level security, behind the same adapter family. Set COMMERCE_BACKEND=supabase plus SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (server-side only, never prefixed NEXT_PUBLIC_).

Firebase

Firestore runs client-side, which buys realtime carts and a zero-SQL setup, and Firebase Auth is the default identity provider on every backend. Admin mutations are routed through the server so they can be authorized and audited there.

Identity, when it is not Firebase

src/lib/auth is the seam: one function turns a request into { uid, email }, and AUTH_PROVIDER picks who implements it. authjs keeps sessions as rows in the SQL backend you already run — a session that can actually be revoked, and no Firebase project. Both packages load lazily, so a Firebase deployment never pulls them in.

Setup and the reasoning behind failing closed: authentication.

The demo backend

No package at all: src/lib/commerce/demo serves catalog.json, the same 18 products npm run seed writes into a real backend. It is what makes npm run dev show a populated store on a fresh clone, and what lets CI run a production build with no credentials.

UI kit

The interface is built from shadcn/ui components copied into src/components/ui/, wrapping Radix primitives for accessible behaviour and styled with Tailwind. They live in the repo, so you own and edit them.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": { "components": "@/components", "utils": "@/lib/utils" }
}

Radix ships one package per primitive; the full list is in package.json (accordion, alert-dialog, aspect-ratio, avatar, checkbox, collapsible, dialog, dropdown-menu, label, menubar, navigation-menu, popover, radio-group, scroll-area, select, separator, slot, switch, tabs, toast, tooltip). Two related helpers ship alongside them:

There is deliberately no input-masking package. react-input-mask reached the DOM through ReactDOM.findDOMNode in componentDidMount, which React 19 removed, so every form with a phone field threw on mount and fell to its error boundary — taking the guest checkout dialog with it. src/lib/phone-mask.ts replaces it with a pure function the mask and its validation pattern are both derived from, which is why they cannot drift apart and why the behaviour is testable without a DOM.

Fonts

Two families, loaded in src/app/[locale]/layout.tsx and exposed as CSS variables the Tailwind config reads.

Geist comes from its own package rather than next/font/google, and globals.css aliases its variables onto the design tokens.

Payments

With STRIPE_SECRET_KEY set, a priced cart gets a Checkout button. POST /api/checkout re-reads every product and variant server-side and prices the session in the store's base currency, so nothing the browser sends can move an amount. POST /api/webhooks/stripe verifies the signature and records the order through the active backend — Postgres, Supabase, or Firestore — keyed by the session id so a retried delivery cannot duplicate it, and consuming the stock it sold in the same transaction. See payments.

Email

Without RESEND_API_KEY the store runs normally and skips email. See email notifications.

Documentation

This site is Fumadocs, compiled by a postinstall step.

Testing and tooling

Three suites, none of which needs a credential, and each of which can prove something the one before it cannot: Testing covers what each is for and which to run.

These docs are part of what the first suite checks — docs-versions.test.ts is why the version in every row above matches package.json, and it fails the build when it does not.

package.json is the authority on all of them, including the e2e:* steps test:e2e composes.

Next steps