Reference

Environment variables

Every environment variable the storefront reads, with its purpose, whether it is required, its default and an example.

The storefront reads these from apps/storefront/.env locally (template: apps/storefront/.env.example), from the Cloudflare dashboard on Workers, or from the service environment on a Node host. Variables starting with NEXT_PUBLIC_ are compiled in at build time; the rest are read by the server. Explanations with examples are in Configuration.

Core

Variable	Purpose	Required	Default	Example
`AUTH_SECRET`	Signs and encrypts the sign-in session cookie.	Yes, in every mode	none	output of `openssl rand -base64 32`
`SITE_URL`	The storefront’s public origin. Builds canonical addresses, sharing tags, language links, `sitemap.xml`, `robots.txt` and `llms.txt`. A path is ignored.	Yes, in production	`http://localhost:3000` (or `PORT`) outside production; none in production	`https://shop.example.com`
`COMMERCE_SOURCE`	Which backend. `woocommerce` for a real store; unset, `mock` or `fake` for Demo Mode. Any other value stops the app.	No	unset (Demo Mode)	`woocommerce`
`WOO_STORE_URL`	The WordPress site, no trailing slash. Also serves the blog and the Companion plugin’s public endpoints.	Yes, when `COMMERCE_SOURCE=woocommerce`	none	`https://cms.example.com`
`RSC_API_URL`	The Companion plugin’s REST base. Sign-in falls back to `WOO_STORE_URL`; newsletter, contact form, profile photo and compare sync use this value directly.	Yes, in WooCommerce mode	`http://retail-store.test/wp-json/retail-store-companion/v1`	`https://cms.example.com/wp-json/retail-store-companion/v1`
`PORT`	Port for `pnpm start` and the development default of `SITE_URL`.	No	`3000`	`3001`

WooCommerce connection

Variable	Purpose	Required	Default	Example
`WOO_CONSUMER_KEY`	WooCommerce REST key for store-level reads: selling and shipping countries, product facts for express checkout on product pages.	Recommended	none	`ck_…`
`WOO_CONSUMER_SECRET`	The secret half of the REST key pair.	Recommended	none	`cs_…`
`STOREFRONT_SHARED_SECRET`	Signs each shopper’s IP address so WordPress’s payment rate limits count shoppers. Must equal `RSC_STOREFRONT_SHARED_SECRET` in `wp-config.php`. Needs a proxy that sets `X-Forwarded-For`.	Recommended in production	none (nothing signed)	output of `openssl rand -hex 32`
`WOO_MULTILINGUAL_PARAM`	Query parameter the multilingual plugin reads, so catalogue content comes back in each Locale.	No	unset (off)	`lang`
`WOO_REQUEST_TIMEOUT_MS`	How long one request to the store may take. A timed-out checkout is followed up before the shopper can pay again.	No	`30000`	`45000`
`WOO_CONNECT_TIMEOUT_MS`	Connection timeout for requests to the store. Node hosts only.	No	`30000`	`60000`
`WOO_DEFAULT_PER_PAGE`	Page size when a request does not ask for one.	No	`20`	`24`
`WOO_INSECURE_TLS`	Development and private staging only: skip certificate checks for store requests, and for the image optimiser outside production.	No	off	`1`
`WOO_CUSTOMER_ID`	Legacy stand-in customer for adapter testing. Superseded by real sign-in; leave empty.	No	none	none
`WOO_CUSTOMER_TOKEN`	Legacy stand-in customer token. Superseded; leave empty.	No	none	none

Look, languages and behaviour

Variable	Purpose	Required	Default	Example
`STOREFRONT_LOCALES`	Ordered Locale list. The first is served without a prefix; the others under `/{locale}`. Invalid values fall back to English.	No	`en`	`en,ar`
`STOREFRONT_TEMPLATE_FAMILY`	The Template Family. An unknown name fails with an error.	No	`default`	`default`
`HOME_SECTIONS`	Which Home page sections render, in order. Ids: `hero`, `categories`, `new-arrivals`, `season-sale`, `best-sellers`, `todays-deals`, `brands`, `trending`, `callout`, `recently-viewed`, `promo-banners`, `daily-essentials`, `reviews`, `blog`.	No	all 14, in that order	`hero,new-arrivals,todays-deals,callout`
`HOME_PRODUCT_CAROUSEL_LIMIT`	Most products in each Home product rail, 1 to 100.	No	`12`	`10`
`HOME_CATEGORIES_LIMIT`	Most categories in the Home category row, 1 to 100.	No	`12`	`8`
`DISTRUCTION_FREE_CHECKOUT`	Minimal header and footer on checkout and order confirmation. Accepts `on`, `true`, `1`, `yes`. The spelling is intentional.	No	off	`on`
`STOREFRONT_CUSTOM_SCRIPTS`	`off` (or `false`, `0`, `no`) stops the WordPress header and footer scripts being injected. Use on staging, preview and local.	No	on	`off`
`NEXT_PUBLIC_PROMO_MODAL`	`0` turns off the first-order promo popup for this deployment.	No	on	`0`
`NEXT_PUBLIC_FACEBOOK_APP_ID`	Enables “Share on Messenger” on product pages. Empty hides Messenger.	No	empty	`1234567890`
`DEMO_TURNSTILE_SITE_KEY`	Demo Mode only: show and enforce Turnstile on review, reply and stock-alert forms. Use a Cloudflare test site key.	No	none	`1x00000000000000000000AA`

Proxies and development

Variable	Purpose	Required	Default	Example
`AUTH_TRUST_HOST`	Tells Auth.js to trust the forwarded host behind a proxy or tunnel.	Recommended behind a proxy	unset	`true`
`DEV_ALLOWED_ORIGINS`	`pnpm dev` only: extra hosts allowed to load the dev server’s scripts (LAN address, tunnel). Comma-separated, wildcards allowed.	No	none	`192.168.1.20,*.trycloudflare.com`
`NODE_EXTRA_CA_CERTS`	Node’s own variable: trust an extra certificate authority, such as a local `.test` CA. Set in the shell, not in `.env`.	No	none	`/path/to/your-local-ca.pem`

Testing and CI

These are for the test suites and CI. Do not set them on a real deployment.

Variable	Purpose	Required	Default	Example
`WOO_CONTRACT`	Runs the contract suite against a real WooCommerce store. It adds to carts and places orders: use a disposable store in test mode only.	No	off	`1`
`WOO_CONTRACT_STRIPE_SECRET_KEY`	A Stripe test secret key for the contract run. The storefront never uses it.	No	none	`sk_test_…`
`WOO_CONTRACT_EXPRESS_PAGES`	Pages the test store has express wallets switched on for.	No	none	`product,cart,checkout`
`WOO_CONTRACT_BILLING`	JSON billing details the test store accepts.	No	a Berlin, DE address	`{"country":"US", …}`
`DEMO_NOW`	Pins Demo Mode’s clock (ISO 8601) outside production, for predictable “Today’s deals”.	No	the real clock	`2026-07-23T12:00:00+02:00`
`NEXT_PUBLIC_STRICT_I18N`	`1` makes a missing translation key throw instead of falling back.	No	off	`1`
`CI`	Turns on Playwright retries and the GitHub reporter. Set by CI.	No	unset	`true`

Demo Mode switches

These make the Fake Adapter behave like a backend that lacks a feature, so the smoke and contract suites can test how the storefront degrades.

Variable	Effect when set
`FAKE_EMBEDDED_PAYMENT_OFF=1`	No on-page card, PayPal or express payment; only offline methods
`FAKE_ADDRESS_BOOK_OFF=1`	No Address Book; accounts fall back to one billing and one shipping address
`FAKE_EMPTY_CATEGORY=1`	Adds a category with no products
`FAKE_POLICY_PAGES_OMIT=cookies,terms`	The listed policy pages have no content and answer 404
`FAKE_THEME_CUSTOM_SCRIPTS=1`	The demo backend sends inline header and footer scripts
`FAKE_THEME_DOCLESS=1`	The demo backend sends no header or footer layout, so the storefront falls back to its built-in ones
`FAKE_THEME_OMIT_HEADER=1`	Another name for `FAKE_THEME_DOCLESS`

GitHub Actions secrets

The WooCommerce contract (payment) workflow, weekly and on demand, needs these repository secrets: WOO_CONTRACT_STORE_URL, WOO_CONTRACT_CONSUMER_KEY, WOO_CONTRACT_CONSUMER_SECRET, WOO_CONTRACT_STRIPE_SECRET_KEY, and optionally the repository variable WOO_CONTRACT_BILLING.

Set by the framework

Do not set these yourself: NODE_ENV, NEXT_RUNTIME, NEXT_PRIVATE_STANDALONE (set by OpenNext during a Cloudflare build) and NODE_TLS_REJECT_UNAUTHORIZED (set to 0 automatically in development when WOO_INSECURE_TLS is on).

ConfigurationThe look and behaviour variables, with examples.

wp-config constantsThe WordPress-side secrets and settings.

DeploymentWhere to set variables on each host.

Storefront Playbook · Built by weLabsFeatures FAQ Talk to us