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

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.

Both sign-in methods are used by the storefront: Google sign-in and passwordless email-link sign-in. Customer records are created in the customers collection on first login.

Configure environment variables

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

cp .env.example .env.local

The only variables you must set to run the store 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.

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 Firestore 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.

Because firestore.rules blocks client-side writes to the products collection, the script uses the Firebase Admin SDK and needs a service-account key.

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

npm run seed -- --dry-run

Then get a key from Firebase console → Project settings → Service accounts → Generate new private key, save it outside the repo (it is git-ignored; never commit it), and point the script at it with either variable:

FIREBASE_SERVICE_ACCOUNT=/path/to/service-account.json npm run seed
# or, using Google application-default credentials:
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json npm run seed

The project id is read from the service-account JSON automatically. With application-default credentials, set FIREBASE_PROJECT_ID (or rely on NEXT_PUBLIC_FIREBASE_PROJECT_ID from .env.local). The script is idempotent: products use deterministic ids and are overwritten in place, and featured copies are cleaned up before being re-added, so re-running never creates duplicates.

Grant yourself admin access

The admin dashboard lives at /admin and is gated by a role — being signed in is not enough. Access is granted by adding your user id to the admins collection in Firestore:

1. Sign in to the store once at http://localhost:3000/login so your user exists in Firebase Auth.
2. In Firestore, create a document in the admins collection whose document id is your user id (shown on the /admin access-denied screen, or in Firebase Auth → Users). The document body can be empty.
3. Reload — the Admin entry appears in the account menu, and /admin unlocks.