Tech Stack

This boilerplate is a modular, quote-based ecommerce starter built on Next.js 14 with the App Router. Everything you need to browse products, build a cart, and submit quote requests works out of the box against Firebase — and every heavier dependency (SQL databases, Stripe payments, transactional email) is optional and env-gated, so you only pay for the complexity you actually turn on.

All versions below are copied verbatim from package.json. Treat that file as the source of truth if a version ever drifts from this page.

The optional / env-gated philosophy

The store's default path needs no payment processor, no SQL database, and no email provider. Those integrations activate only when you set their environment variables:

The store is quote-based by default: browse → cart → submit a quote request, no payment required. Stripe, Resend, and the SQL adapters are additive layers on top of that core. See environment variables for the full list.

Core stack

These are the load-bearing dependencies every install uses.

Why Next.js 14 + App Router

The App Router lets server components fetch catalog data and resolve locale, currency, and theme server-side on first paint (no flash), while route handlers under src/app/api/* provide the Public Store API, the checkout endpoint, and the commerce RPC bridge. Server-rendered pages also make the SEO pack (sitemap, robots, JSON-LD) straightforward.

UI kit — shadcn/ui + Radix UI

The interface is built from shadcn/ui components — 30+ primitives copied into src/components/ui/ — which wrap Radix UI for accessible, unstyled behavior and style it with Tailwind. Because the components live in your repo (not node_modules), you own and can edit every one.

The shadcn configuration lives in components.json:

{
  "$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 packages are pulled in per primitive. A representative selection from package.json:

The full set (accordion, alert-dialog, aspect-ratio, avatar, checkbox, collapsible, label, menubar, radio-group, scroll-area, separator, slot, switch, and more) is listed in package.json. Two related UI helpers ship alongside them:

Fonts

Typography combines two families, wired through src/app/[locale]/layout.tsx and exposed as CSS variables the Tailwind fontFamily config reads:

Geist ships as the official geist npm package (it is not in this Next version's Google-font manifest); globals.css aliases its --font-geist-sans / --font-geist-mono variables onto the --font-sans / --font-mono design tokens.

Firebase — the default backend

Firebase is the zero-config default: it provides authentication, the Firestore document database, and file storage, with realtime carts and an all-client data flow. No SQL setup, no Prisma account.

Firebase Auth is the identity provider regardless of which database you choose — swapping backends never changes how users sign in. See choosing a backend and the Firestore data model for details.

Optional SQL backends

The commerce layer (src/lib/commerce) is backend-agnostic: Firebase is one adapter, and two SQL adapters ship behind the same interface. These are server-side only and activate via COMMERCE_BACKEND / NEXT_PUBLIC_COMMERCE_BACKEND.

Prisma tooling is exposed through two npm scripts: npm run prisma:generate and npm run prisma:push.

Optional payments — Stripe

With STRIPE_SECRET_KEY set, carts where every item has a price gain a Checkout button beside the quote flow. POST /api/checkout re-prices items server-side (client prices are never trusted) and creates a variant-aware Checkout Session; POST /api/webhooks/stripe (needs STRIPE_WEBHOOK_SECRET) records the paid order. See payments.

Optional email — Resend + react-email

With no RESEND_API_KEY, the store runs normally and skips email. When enabled, quote submissions notify your team and confirm receipt to the customer; the template lives in src/components/emailing/QuoteEmailTemplate.tsx. See email notifications.

Documentation — Fumadocs

These docs (the page you are reading) are built with Fumadocs, wired via a postinstall step that runs fumadocs-mdx.

Testing — Vitest

Tests run in a plain Node environment — no browser, emulators, or Firebase credentials required — and live in tests/, covering the pure seams of the app (rate limiter, email schemas, Public Store API helpers, cart merging, the commerce surface, and the cn utility). Globals are off, so tests import their APIs explicitly (import { describe, it, expect } from "vitest").

Run them with:

npm test          # CI mode (vitest run)
npm run test:watch

Tooling scripts

The scripts block in package.json ties the stack together:

Linting uses eslint ^8 with eslint-config-next 14.2.4; PostCSS (^8) drives the Tailwind build.

Next steps