Deployment

The boilerplate works out of the box on Vercel: import the repo, set the environment variables from .env.example, and deploy. Any Node host that supports Next.js 16 works too. Stripe payments, Resend emails, and the database adapters are all optional and env-gated — a first deploy needs nothing more than your Firebase web credentials and a sign-in redirect URL, and without Stripe the store is quote-based.

Deploy to Vercel

NEXT_PUBLIC_EMAIL_SIGNIN_REDIRECT_URL=https://shop.example.com/complete-login

The Stripe webhook needs a service account

Stripe order recording happens server-side with the Firebase Admin SDK, which needs privileged credentials that the browser never sees. On Vercel the convenient option is FIREBASE_SERVICE_ACCOUNT_JSON — paste the service-account key's JSON contents (not a file path) directly into the environment variable:

FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"your-project", ... }

The same admin credentials also power the npm run seed demo-data script — see Demo data. Note the SQL backends require FIREBASE_SERVICE_ACCOUNT* too, because Firebase Auth stays the identity provider and its ID tokens are verified server-side.

Configure images for your CDN

Product images (primaryImageURL) render through next/image, so every host they can be served from must be listed in images.remotePatterns in next.config.mjs, or next/image refuses to optimize those URLs. Firebase Storage and the demo photography host ship allowed, so a store that uploads its images needs no change here; add your own CDN or bucket hostname before deploying. Media & image uploads has the config block and a worked example.

Continuous integration

The repository ships its own GitHub Actions workflow at .github/workflows/ci.yml. It runs on pushes to main and on every pull request, cancels superseded runs on the same branch, and splits into two jobs that run in parallel, both on Node 20.

The verify job is the gate — lint, typecheck, build, unit tests, SQLite integration tests:

- name: Lint
  # --max-warnings 0 — warnings are failures here.
  run: npm run lint -- --max-warnings 0

- name: Typecheck
  run: npm run typecheck

- name: Build
  run: npm run build
  # No env needed: with no credentials the commerce layer resolves to the
  # bundled demo backend and src/lib/firebase/config.ts falls back to
  # placeholder values, so the build never needs a real project.

- name: Test
  run: npm test

- name: Test (SQLite integration)
  run: npm run test:sqlite

Two orderings there are deliberate, not accidental:

• Build runs before Test. tests/api-routes-dynamic.test.ts asserts that every API route stayed dynamic by reading the prerender manifest — a build artifact. Run the tests first and that suite silently skips itself.
• The SQLite integration suite runs last. It generates a Prisma client, and the build above has to prove the project builds without one.

The build step needs no environment variables. The optional SQL packages are external, so the default build never requires @prisma/client, pg, better-sqlite3, or a DATABASE_URL.

The e2e job drives Playwright against a production build:

- name: Install Playwright (chromium)
  run: npx playwright install --with-deps chromium

- name: Run end-to-end tests
  run: npm run test:e2e

It is a separate job so that a browser install and a second production build cannot slow down — or fail — the gate above, and so the two run at the same time rather than in sequence. Chromium only: the specs guard flows, not rendering engines, and a second browser would double the minutes to re-verify the same server-side behaviour. It needs no credentials either — COMMERCE_BACKEND=sqlite puts the store on a file database and AUTH_PROVIDER=authjs keeps sessions in it, so there is no Firebase project and no Stripe account in the loop (e2e/env.ts holds the whole environment, e2e/scripts/provision.ts seeds the catalog and accounts). npm run test:e2e provisions before it builds, because next build reads the catalog. The HTML report uploads on every run; screenshots, video, and traces only on a failure.

For what each suite can actually prove, and which one to reach for on a given change, see Testing.

Production readiness

Related