Install the storefront

This page gets the storefront running on your machine in Demo Mode: a complete store with a catalogue, cart, checkout and a demo account, all in memory. You need no WordPress for any of it. Connecting a real WooCommerce site comes next, in Connect WooCommerce.

Before you start

You need	Version	Notes
Node.js	22 or newer	The repository’s engines field requires it. Older versions fail with syntax errors.
pnpm	10.33.0	Pinned in package.json. Corepack, which ships with Node, installs it for you. npm and Yarn are not supported.
Git	Any current version	With access to the private repository (see below).
Playwright Chromium	Installed by a command below	Only needed to run the browser test suite.

Note

The repository welabs-ltd/retail-store-frontend is private. weLabs grants access per project; ask your weLabs contact to add your GitHub account before you clone.

Check your Node version first:

node --version   # must print v22 or later

If it prints an older version, install Node 22 or newer and make sure it comes first on your PATH. On a Mac with Homebrew, that usually means:

export PATH="/opt/homebrew/opt/node/bin:$PATH"

Install and run Demo Mode

1. Clone the repository.

   git clone git@github.com:welabs-ltd/retail-store-frontend.git
   cd retail-store-frontend

2. Turn on Corepack. It provides the exact pnpm version the repository pins.

   corepack enable

3. Install dependencies. One install covers the app and every package in the workspace.

   pnpm install

4. Create your environment file. The app reads apps/storefront/.env.

   cp apps/storefront/.env.example apps/storefront/.env

   The template already sets COMMERCE_SOURCE=mock, which is Demo Mode.

5. Set AUTH_SECRET. It signs the sign-in session cookie and is required in every mode. Generate a value:

   openssl rand -base64 32

   Paste it into apps/storefront/.env:

   AUTH_SECRET=paste-the-generated-value-here

6. Start the dev server.

   pnpm dev

   Open http://localhost:3000. You have a working store.

Try the demo store

Sign in, shop and pay with these. No real money moves and no payment provider is contacted.

What	Value
Demo account	demo@retail.store / demo1234
Coupon	DEMO10 (10% off)
Card that is approved	4242 4242 4242 4242
Card that is declined	4000 0000 0000 0002
Card that asks for a bank check (3-D Secure)	4000 0000 0000 3220

Any future expiry date and any three-digit security code work. The full list of seeded data is in Demo data.

Caution

Demo Mode keeps everything in server memory. Restarting the dev server resets carts, orders, new accounts and reviews.

Run a bilingual demo

The storefront ships English and Arabic, with full right-to-left layout. Start it with both Locales:

STOREFRONT_LOCALES=en,ar pnpm dev

English is served at / and Arabic under /ar, with a language switcher in the header. The first Locale in the list is the default and has no prefix. To make it permanent, set STOREFRONT_LOCALES=en,ar in apps/storefront/.env. See Configuration for the rules.

Run the checks

These are the same checks CI runs on every push. Run them from the repository root.

pnpm typecheck   # strict TypeScript across every workspace package
pnpm lint        # ESLint, including the architecture and right-to-left rules
pnpm test        # Vitest: the contract suite and package tests, no network
pnpm test:e2e    # Playwright smoke suite, always in Demo Mode
pnpm build       # production build

Install the Playwright browser once before the first pnpm test:e2e:

pnpm --filter @welabs/retail-storefront exec playwright install chromium

Tip

Stop pnpm dev before running pnpm test:e2e. The suite starts its own dev server in Demo Mode on port 3105 with a fixed test configuration, whatever your .env says.

Work against a local WordPress

If your WordPress runs locally on a .test domain (Laravel Herd, Valet and similar tools), Node will not trust its self-signed certificate. You have two options.

Trust the local CA (preferred)

Point Node at your local certificate authority’s root certificate. Node reads this variable when it starts, so set it in your shell, not in .env:

export NODE_EXTRA_CA_CERTS="/path/to/your-local-ca.pem"
pnpm dev

Herd and Valet keep their CA certificate in their own configuration folder.

Skip TLS checks (development only)

Add this to apps/storefront/.env:

WOO_INSECURE_TLS=1

It turns off certificate checks for requests to WooCommerce, and for the image optimiser outside production.

Danger

Never set WOO_INSECURE_TLS on a production or public staging deployment. Fix the certificate instead.

Product images from a local backend work without extra settings: when WOO_STORE_URL points at a .test, localhost or private-network address, the image optimiser is allowed to fetch from it in development.

Open the dev server from another device

Next.js 16 blocks the dev server’s scripts for any host other than localhost. If you open the store from a phone on your network or through a tunnel, the page renders but nothing is clickable. List the extra hosts in apps/storefront/.env:

DEV_ALLOWED_ORIGINS=192.168.1.20,*.trycloudflare.com

The list is comma-separated and accepts wildcards. It only affects pnpm dev, never a production build. Behind a tunnel, also set AUTH_TRUST_HOST=true so sign-in sees the tunnel’s address instead of localhost.

Next steps

Connect WooCommerceSwitch from Demo Mode to your WordPress site.

ConfigurationLanguages, Home sections and checkout options.

TroubleshootingFixes for common install and run problems.