Environment Variables
Which variables exist, what reads them, and does a change need a rebuild? This page lists the environment variables that the Storefront Application V3 and the SCAYLE packages it runs on read. The server reads most of them when it starts, so a new value takes a restart. Vite reads the build-time variables while it builds, so a new value takes a rebuild. Build time and runtime explains why the two differ.
Each table's last column says what a change needs:
- Restart: the server picks up the new value when its process restarts.
- Rebuild: you build and deploy again.
Under pnpm dev, the runtime and local development variables come from your .env file, and .env.example in your project lists most of them with comments. In production, they come from your container or hosting environment. Variables that only test and content tooling read, such as those of the Playwright suite, aren't listed.
Naming conventions
- Prefix a variable you add with
STOREFRONT_. You can then grep for everything the application depends on. The variables below without the prefix belong to a specific tool or platform, such asOTEL_*for OpenTelemetry,SCAYLE_KV_*for the KV driver, and the CMS vendor credentials. - Name a country-scoped variable after the country code, as
STOREFRONT_COUNTRIES_<CODE>_<NAME>: writeSTOREFRONT_COUNTRIES_DE_CHECKOUT_TOKEN, not a name with the numeric shop country ID. The tables write the code as<CODE>. The shipped config usesDE,US, andAT. - Read a variable you add in
storefront.config.tswhere you can, so it's validated with the rest of the config. See Add your own config field. - Never give a secret the
VITE_prefix. Vite inlines everyVITE_*value into the browser bundle. See What reaches the browser.
Required
storefront.config.ts reads every variable in this table, and none has a default: the server refuses to start while one is unset. Set the four STOREFRONT_COUNTRIES_<CODE>_* variables once for every country in countries.
| Variable | Sets | Change needs |
|---|---|---|
STOREFRONT_TENANT_SPACE | tenantSpace, your tenant space as it appears in the SCAYLE Panel URL | Restart |
STOREFRONT_SHOP_KEY | shopKey, your parent shop key from SCAYLE Panel ➜ Shops | Restart |
STOREFRONT_API_KEY | storefrontApiKey, the SCAYLE Storefront API token | Restart |
STOREFRONT_OAUTH_CLIENT_ID | oauth.clientId | Restart |
STOREFRONT_OAUTH_CLIENT_SECRET | oauth.clientSecret | Restart |
STOREFRONT_SESSION_SECRET | session.secret, at least 32 characters | Restart |
STOREFRONT_COUNTRIES_<CODE>_SHOP_COUNTRY_ID | The country's shopCountryId | Restart |
STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_USER | The country's checkout.user | Restart |
STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_TOKEN | The country's checkout.token | Restart |
STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_SECRET | The country's checkout.secret | Restart |
Validation at startup lists what the startup check misses, such as an empty STOREFRONT_API_KEY.
Optional settings
| Variable | What it does | Default | Change needs |
|---|---|---|---|
STOREFRONT_COUNTRY_SELECTOR | countrySelector in storefront.config.ts: path or path_except_default. The domain selector takes a code change, see Switch the country selector. | path | Restart |
STOREFRONT_DOMAIN | The top-level domain in storefront.config.ts: the public host for absolute URLs under the path selectors, as a bare host. See Public origin. | Unset, the request host | Restart |
Integrations
Each feature page lists its own variables with their defaults and what a change needs.
- OpenTelemetry: the standard
OTEL_*variables andUNSTORAGE_COMPRESSION_OTEL_TRACEare in OpenTelemetry. - CMS:
CMS_PROVIDERselects the provider when Vite builds. The server checks the credentials of that provider when it starts, and a missing required one stops the boot. The credentials are in Storyblok, Contentful, Contentstack, and Amplience.STOREFRONT_CMS_ALLOW_DRAFTSis in CMS. - Content Security Policy:
STOREFRONT_CSP_REPORT_URIis in Security Headers. - Google Tag Manager and Usercentrics:
storefront.config.tsreadsSTOREFRONT_GTM_IDandSTOREFRONT_USER_CENTRICS_APP_IDintopublicFields, so their values reach the browser. See Google Tag Manager and Consent Management. - Subscriptions:
STOREFRONT_COUNTRIES_<CODE>_SUBSCRIPTION_ENABLEDturns the add-on on for one country. See Subscriptions.
Runtime SDK
The SCAYLE packages read these from process.env on the server.
Server
| Variable | What it does | Default | Change needs |
|---|---|---|---|
PORT | The production server entry that @scayle/storefront-build generates. The port it listens on. pnpm dev listens on server.port from vite.config.ts instead. | 3000 | Restart |
HOST | The same entry. The address it binds to. | 0.0.0.0 | Restart |
Logging
The logger in @scayle/storefront reads these when the first logger is created. See Format and levels and Redaction.
| Variable | What it does | Default | Change needs |
|---|---|---|---|
STOREFRONT_LOG_FORMAT | pretty for readable lines. Any other value writes JSON. | json | Restart |
STOREFRONT_LOG_LEVEL | The minimum level: debug, info, warn, or error. Any other value falls back to info. | info | Restart |
STOREFRONT_LOG_REDACT_KEYS | Comma-separated keys to redact, merged with the built-in list. | Unset | Restart |
Cache and SCAYLE KV
Sessions and the data cache share one store. @scayle/storefront reads the STOREFRONT_* variables, and the SCAYLE KV driver it depends on, @scayle/unstorage-scayle-kv-driver, reads the SCAYLE_KV_* ones.
| Variable | What it does | Default | Change needs |
|---|---|---|---|
STOREFRONT_CACHE_DISABLED | true turns the data cache off: getOrSet runs its fetcher every time and stores nothing. The response cache headers don't change. | Off | Restart |
STOREFRONT_CACHE_COMPRESSION | Compression of stored values: brotli, gzip, deflate, or none. Sessions share the store, so changing it on a live shop can leave existing sessions unreadable. | brotli | Restart |
STOREFRONT_KV_DISABLE_CLUSTER_MODE | true connects to a single Redis or Valkey instance, such as the one from docker-compose.yml, instead of a cluster. | Off, cluster mode as SCAYLE KV runs | Restart |
SCAYLE_KV_HOST | Host of SCAYLE KV, or of your Redis or Valkey instance. | localhost | Restart |
SCAYLE_KV_PORT | Its port. | 6379 | Restart |
SCAYLE_KV_USER, SCAYLE_KV_PASSWORD | Its credentials. | Unset | Restart |
SCAYLE_KV_TLS | true connects over TLS. | Off | Restart |
SCAYLE_KV_BASE | A prefix for every key the store writes. | Unset | Restart |
Build time
Vite reads these while it builds, through vite.config.ts or the plugins of @scayle/storefront-build, and compiles the result into the output. Set them in the environment that runs pnpm build, such as your CI job or a Docker build argument, because the build doesn't read them from .env. CMS_PROVIDER, listed on the CMS page, is a build-time variable too and the one exception: vite.config.ts reads it through Vite's loadEnv, so a value in .env also works.
| Variable | What it does | Default | Change needs |
|---|---|---|---|
SCAYLE_BUILD_ID | @scayle/storefront-build. Puts the client assets under assets/<id>/, becomes the Inertia asset version the browser compares to detect a new deployment, and prefixes data cache keys, so a new build starts with an empty cache. Set it to your commit SHA or build number. | Unset, plain assets/ and no prefix | Rebuild |
DISABLE_POWERED_BY_HEADER | @scayle/storefront-build, into import.meta.env.DISABLE_POWERED_BY_HEADER. Any non-empty value, false included, drops the X-Powered-By response header. | Unset, the header is sent | Rebuild |
ANALYZE_BUNDLE | vite.config.ts. true writes a Markdown bundle report for each build: bundle-analysis-client.md in .output/public and bundle-analysis-ssr.md in .output/server. | Unset | Rebuild |
Vite defines import.meta.env.DEV, PROD, MODE, and SSR itself, so you never set them.
Local development
These apply to pnpm dev only. The dev server reads the certificate files at startup and stops with an error that names the expected paths when one is missing. It skips that check when the CI environment variable is set, and under Vitest and Storybook. Set Up Your Storefront shows how to create the files.
| Variable | What it does | Default | Change needs |
|---|---|---|---|
HTTPS_CERT, HTTPS_KEY | vite.config.ts. Paths to the TLS certificate and key of the dev server. | certs/localhost.crt, certs/localhost.key | Restart |
STOREFRONT_DETECTED_COUNTRY | CountryService in @scayle/storefront. Stands in for the CF-IPCountry header that country detection reads. A production build ignores it. See Country Detection. | Unset | Restart |