Environment Variables

The boilerplate is configured entirely through environment variables. Copy the template and fill in the values you need:

cp .env.example .env.local

Nothing here is required to boot. With no NEXT_PUBLIC_FIREBASE_PROJECT_ID and no backend named, the storefront serves the built-in demo catalog, so a fresh clone renders a populated store before any setup — see commerce backend selection. The Firebase web credentials and the email sign-in redirect URL are what the default real deployment needs. Everything else is optional and feature-gated: leaving an optional variable empty disables that feature gracefully, with no crash and no build failure. The store's default mode is quote-based (browse → cart → submit a quote request), so payments, transactional email, and SQL backends all stay off until you opt in.

Quick reference

"Yes" means required for the default Firebase deployment; the demo backend needs none of them.

Firebase web credentials

Firebase Auth is the default identity provider, and on a Firestore data backend the only one (firestore.rules gate on request.auth). On a SQL backend you can switch to Auth.js and drop Firebase entirely — see authentication. Firebase is also the commerce backend that takes over implicitly once a project id is set and no backend is named; every other backend is opt-in. These seven values come from the Firebase console → Project settings → Your apps. They are NEXT_PUBLIC_* because Firebase web credentials are meant to be public — access control lives in your Firestore security rules, not in these keys.

Email sign-in redirect

The storefront uses Firebase passwordless (email-link) sign-in. After a user clicks the link in their inbox, Firebase redirects them back to this absolute URL to complete authentication.

Identity provider (optional)

Firebase Auth answers "who is calling?" unless AUTH_PROVIDER says otherwise. authjs puts sessions in your SQL database and drops the Firebase project entirely — authentication covers what that changes, and why it only works on a SQL backend.

Resend email notifications (optional)

Transactional email is powered by Resend and is entirely optional. When RESEND_API_KEY is empty, the POST /api/quotes/notify and POST /api/notifications/status endpoints skip sending and respond { skipped: true } — the quote flow itself is unaffected.

The fallbacks are applied server-side in src/app/api/quotes/notify/route.ts:

const from = process.env.RESEND_FROM_EMAIL || "onboarding@resend.dev";
const adminRecipient =
  process.env.QUOTE_NOTIFICATION_EMAIL || siteConfig.contact.email;

Rate limiting (optional)

/api/checkout, /api/quotes/notify and /api/notifications/status are rate limited per client IP. Without these variables the counters live in the server process, which on serverless means per instance — set them to move the counters to a shared store so the limit actually holds. Values come from the Upstash console → your database → REST API.

Seed service account (optional)

npm run seed (scripts/seed.ts) writes the demo catalog through whichever backend is selected, using that backend's own credentials — DATABASE_URL for Postgres/SQLite, SUPABASE_* for Supabase, and Firebase Admin credentials for Firestore. Only the Firestore path needs the variable below: point it at a service-account JSON file from the Firebase console → Project settings → Service accounts → Generate new private key.

Stripe Checkout (optional)

Stripe adds a real "Checkout" button alongside the quote flow. The Stripe client is instantiated lazily (src/lib/stripe.ts), so when STRIPE_SECRET_KEY is unset the store stays quote-only and the Checkout button simply does not appear.

export function isStripeEnabled(): boolean {
  return Boolean(process.env.STRIPE_SECRET_KEY);
}

Newsletter storage (optional)

The home-page signup form posts to POST /api/newsletter, which resolves a provider from src/lib/newsletter — the collection no longer accepts writes from the browser. The endpoint's validation and rate limiting are covered in storefront → newsletter signup.

Commerce backend selection

The commerce data layer (src/lib/commerce) is backend-agnostic. Firebase is the default and runs entirely client-side. Selecting a SQL backend routes the browser through the /api/commerce RPC route, where a privileged server adapter runs. Firebase Auth stays the default identity provider on every backend — its ID token is verified server-side via firebase-admin, so the FIREBASE_SERVICE_ACCOUNT* credentials are required for the SQL backends too, unless AUTH_PROVIDER=authjs replaces it.

Two variables must agree:

• demo: the built-in fixture catalog — no backend at all. Browsing, search, and the cart work; writes (quotes, admin, profile) are rejected with an explanatory error. This is also what an unset value falls back to when NEXT_PUBLIC_FIREBASE_PROJECT_ID is empty. Browser-side only: leave COMMERCE_BACKEND empty, since the server var has no demo case and throws on one.
• firebase (or unset, with a project id): pure client-side Firebase — no RPC route, no SQL variables needed.
• sqlite | postgres | supabase: set both variables to the same value and provide the matching credentials below.

Admin writes on Firebase

On the Firebase backend, admin mutations are routed through /api/commerce so the server can re-check admin status and record an audit entry the acting admin cannot skip — which needs the FIREBASE_SERVICE_ACCOUNT* credentials above.

Supabase adapter

Set when COMMERCE_BACKEND=supabase. Values come from Supabase → Project Settings → API. See the Supabase adapter guide.

Prisma adapter — Postgres or SQLite

Set when COMMERCE_BACKEND is postgres or sqlite. Read by both the Prisma CLI (prisma.config.ts) and the runtime adapter (src/lib/commerce/server/prisma/index.ts). See the Postgres/Prisma and SQLite guides.

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

Related