Storefront setup

This section is for whoever installs and runs the storefront: an agency developer, a client’s IT team or a freelancer. It takes you from a fresh clone to a deployed store, mostly through commands and environment variables. Everything the Store Owner manages day to day lives in WordPress and is covered in the Store admin guides.

What you’ll do

1. Install the monorepo and run it in Demo Mode. No WordPress is needed, so this is the quickest way to see the whole store working.
2. Connect it to your WooCommerce site through the Companion plugin.
3. Configure languages, Home page sections and checkout behaviour, which are set per deployment with environment variables.
4. Set the store identity that lives in code: the store name, tagline and the About and Find a Store pages.
5. Deploy to Cloudflare Workers or any Node host.
6. Launch with the go-live checklist.

The monorepo at a glance

The storefront is a pnpm workspace. You run and deploy one app; the packages beside it are compiled into that app, so they have no build step of their own.

• Directoryretail-store-frontend/

  • Directoryapps/

    • Directorystorefront/ the Next.js 16 app you run and deploy

      • .env.example template for your .env
      • wrangler.jsonc Cloudflare Worker settings
      • open-next.config.ts OpenNext build settings
      • Directorylib/

        • Directoryconfig/ store identity and page content

          • …
  • Directorypackages/

    • Directorycommerce-core/ the shared commerce model and its contract tests

      • …
    • Directoryadapter-woocommerce/ the only code that talks to WooCommerce

      • …
    • Directoryadapter-woocommerce-invoice/ PDF invoice support

      • …
    • Directoryadapter-fake/ the in-memory store behind Demo Mode

      • …
    • Directorystorefront-ui/ shared visual components

      • …
    • Directorytemplates/ page templates (Template Families)

      • …
  • Directorydocs/

    • Directoryadr/ architecture decision records

      • …
  • package.json pins Node 22+ and pnpm 10.33.0
  • pnpm-lock.yaml

Developers who want the reasoning behind this layout should read Architecture.

Demo Mode and WooCommerce mode

The storefront always runs in one of two modes, chosen by COMMERCE_SOURCE.

Demo Mode

COMMERCE_SOURCE unset, mock or fake. A complete store with a built-in catalogue, cart, checkout with demo payments and a demo account. Nothing to connect. Data lives in memory and resets when the server restarts. Use it to evaluate, demo or develop.

WooCommerce mode

COMMERCE_SOURCE=woocommerce. Products, cart, orders and accounts come from your WordPress site, through WooCommerce and the Companion plugin. This is how a real store runs.

Tip

Start every new project in Demo Mode. If Demo Mode works and WooCommerce mode does not, the problem is in the connection, not on your machine. See Demo Mode for what the demo store includes.

Where settings live

What	Where it is set	When a change shows
Colours, header, footer, Home page content, SEO, policies, scripts	WordPress: StoreFront → Settings	Within about 5 minutes, no redeploy
Payment gateways and their test/live mode	WordPress: WooCommerce → Settings → Payments	On the next checkout, no redeploy
Social sign-in and Turnstile	WordPress: StoreFront → Settings → Authentication	No redeploy
Languages, Home sections, checkout chrome, Template Family	Storefront environment variables	After a redeploy or restart
Store name, tagline, About and Find a Store content	Storefront code in apps/storefront/lib/config/ and the Find a Store page	After a rebuild and redeploy

Caution

Payment keys, social sign-in credentials and Turnstile keys belong in WordPress. The storefront reads what it needs from there, so never put them in the storefront’s environment.

Next steps

InstallClone the repository and run the store in Demo Mode.

Connect WooCommercePoint the storefront at your WordPress site.

DeploymentShip to Cloudflare Workers or a Node host.

Go-live checklistEverything to check before you open the doors.