Quick Start

Clone and install

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

npm install runs a postinstall step (fumadocs-mdx) that generates the type definitions for these docs — that is expected.

Create a Firebase project (identity)

1. Create a project at console.firebase.google.com.
2. Add a Web app and copy its config values (you will paste them into .env.local next).
3. Enable Authentication → sign-in methods: Google and Email link (passwordless).
4. Enable Cloud Firestore — required only if Firestore will also hold your data.

Skipping this step is possible on a SQL backend: set AUTH_PROVIDER=authjs and sign-in runs on Auth.js with session rows in your own database, no Firebase project at all. See authentication for that path; the rest of this page assumes the Firebase default.

Configure environment variables

Copy the example file and fill in your Firebase web-app values:

cp .env.example .env.local

The variables that switch sign-in on are the Firebase NEXT_PUBLIC_* values plus the email sign-in redirect URL:

Set the redirect URL for local development:

NEXT_PUBLIC_EMAIL_SIGNIN_REDIRECT_URL=http://localhost:3000/complete-login

The passwordless email-link sign-in returns the visitor to this absolute URL to finish signing in. In production, set it to your live URL (e.g. https://yourstore.com/complete-login) and make sure that domain is listed under Firebase Auth → Settings → Authorized domains.

Choose where the data lives

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

Supabase is the fourth option — hosted Postgres behind the same adapter family. See choosing a backend for the full comparison.

Run the dev server

npm run dev

Open http://localhost:3000. The storefront renders immediately — the landing page, header, and navigation all work right away. Product grids stay empty until you add catalog data, either by seeding demo data (next step) or by creating products in the admin dashboard.

(Optional) Seed demo data

The repo ships a seed script that fills whichever backend you just chose with 18 demo products (3 per category, matching the slugs in src/config/site.ts) and features 6 of them on the home page. Two of the products carry variants (a size axis and a color axis with a price override) so the variant UI is demoable. They are the same fixture the demo backend serves, so a seeded store shows exactly what the zero-config one did.

First, preview the plan — this needs no credentials and writes nothing:

npm run seed -- --dry-run

Then run it. The script reads .env.local, so if COMMERCE_BACKEND and the credentials are already there, this is the whole command:

npm run seed

COMMERCE_BACKEND=sqlite npm run seed     # or postgres / supabase

The script is idempotent on every backend: products are written by their catalog id and overwritten in place, and stale featured copies are removed before the new ones are added, so re-running never duplicates anything.

Grant yourself admin access

The admin dashboard lives at /admin and is gated by a role — being signed in is not enough. The role is a record keyed by the uid your identity provider issued, stored in whichever backend holds your data:

1. Sign in to the store once at http://localhost:3000/login so your user exists.
2. Add the record for your uid (shown on the /admin access-denied screen, or in Firebase Auth → Users):
   • SQLite: sqlite3 dev.db "insert or ignore into admins (uid) values ('<your-uid>');"
   • Postgres / Supabase: insert into admins (uid) values ('<your-uid>') on conflict (uid) do nothing;
   • Firestore: create a document in the admins collection whose document id is your uid. The body can be empty.
3. Reload — the Admin entry appears in the account menu, and /admin unlocks.