Get started

Headless storefront starter

apps/storefront-starter/ is a production-grade Next.js 14 storefront wired to the Mercentia gateway. Use it as the basis for a custom front-end when Mercentia’s hosted theme isn’t flexible enough.

What’s in the box

  • Next.js 14 with the App Router and React Server Components.
  • Streaming PDP + PLP that fetches via @mercentia/sdk.
  • Cart persisted to a signed cookie + the gateway cart endpoint, so it survives across devices when the customer signs in.
  • Express checkout button using the /checkout/express endpoint.
  • Stripe Elements mount for the standard checkout fallback.
  • Server-side GA4 beacon for page_view and view_item events.

Scaffold

Three equivalent ways to grab the template — pick whichever fits your workflow.

# Fastest — no git history, just the files.
npx degit mercentia/mercentia/storefront-starter my-shop

# Via the Mercentia CLI (once @mercentia/cli is installed globally).
mercentia app create --template storefront my-shop

# Or shallow-clone the monorepo and copy the directory.
git clone --depth=1 https://github.com/mercentia/mercentia.git
cp -R mercentia/storefront-starter my-shop

Then:

cd my-shop
pnpm install
cp .env.example .env.local
pnpm dev

Configure

.env.local:

MERCENTIA_GATEWAY=https://api.mercentia.com
MERCENTIA_STORE_ID=11111111-1111-4111-8111-111111111111
MERCENTIA_PUBLIC_API_KEY=pk_live_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxx

The starter is hosted-agnostic — deploy to Vercel, Cloudflare Pages, or any Node host. Build is pnpm build; the output respects Next.js’s standard .next/standalone.

Build behaviour in the monorepo

The starter is excluded from the root recursive build (pnpm -r build --filter '!storefront-starter') so that the gateway can deploy without requiring the storefront’s env vars to exist in the build environment. CI builds the starter separately with its own env wiring.

Env validation is lazy — it only runs at request time, not at next build time, so a missing MERCENTIA_STORE_ID won’t fail the build. (Useful for the “fork and tweak” workflow.)

Customising

Every page is a normal RSC page. The data layer is @mercentia/sdk (auto-generated from the OpenAPI spec) — you get typed request / response models for every gateway endpoint.

For one-off UI tweaks, edit the page directly. For wholesale redesigns, fork the components in components/ — the SDK and data fetching glue is small enough to keep.

Going to production

Standard checklist:

  • Replace MERCENTIA_PUBLIC_API_KEY with a key scoped to read:catalog + write:cart only.
  • Configure your own domain in Mercentia → Settings → Domains and point its CNAME at your Next.js host.
  • Enable output: 'standalone' if deploying to a Node host without Next.js’s built-in image optimiser.