docs

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 as OTEL_* 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>: write STOREFRONT_COUNTRIES_DE_CHECKOUT_TOKEN, not a name with the numeric shop country ID. The tables write the code as <CODE>. The shipped config uses DE, US, and AT.
  • Read a variable you add in storefront.config.ts where 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 every VITE_* 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.

VariableSetsChange needs
STOREFRONT_TENANT_SPACEtenantSpace, your tenant space as it appears in the SCAYLE Panel URLRestart
STOREFRONT_SHOP_KEYshopKey, your parent shop key from SCAYLE Panel ➜ ShopsRestart
STOREFRONT_API_KEYstorefrontApiKey, the SCAYLE Storefront API tokenRestart
STOREFRONT_OAUTH_CLIENT_IDoauth.clientIdRestart
STOREFRONT_OAUTH_CLIENT_SECREToauth.clientSecretRestart
STOREFRONT_SESSION_SECRETsession.secret, at least 32 charactersRestart
STOREFRONT_COUNTRIES_<CODE>_SHOP_COUNTRY_IDThe country's shopCountryIdRestart
STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_USERThe country's checkout.userRestart
STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_TOKENThe country's checkout.tokenRestart
STOREFRONT_COUNTRIES_<CODE>_CHECKOUT_SECRETThe country's checkout.secretRestart

Validation at startup lists what the startup check misses, such as an empty STOREFRONT_API_KEY.

Optional settings

VariableWhat it doesDefaultChange needs
STOREFRONT_COUNTRY_SELECTORcountrySelector in storefront.config.ts: path or path_except_default. The domain selector takes a code change, see Switch the country selector.pathRestart
STOREFRONT_DOMAINThe 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 hostRestart

Integrations

Each feature page lists its own variables with their defaults and what a change needs.

  • OpenTelemetry: the standard OTEL_* variables and UNSTORAGE_COMPRESSION_OTEL_TRACE are in OpenTelemetry.
  • CMS: CMS_PROVIDER selects 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_DRAFTS is in CMS.
  • Content Security Policy: STOREFRONT_CSP_REPORT_URI is in Security Headers.
  • Google Tag Manager and Usercentrics: storefront.config.ts reads STOREFRONT_GTM_ID and STOREFRONT_USER_CENTRICS_APP_ID into publicFields, so their values reach the browser. See Google Tag Manager and Consent Management.
  • Subscriptions: STOREFRONT_COUNTRIES_<CODE>_SUBSCRIPTION_ENABLED turns the add-on on for one country. See Subscriptions.

Runtime SDK

The SCAYLE packages read these from process.env on the server.

Server

VariableWhat it doesDefaultChange needs
PORTThe production server entry that @scayle/storefront-build generates. The port it listens on. pnpm dev listens on server.port from vite.config.ts instead.3000Restart
HOSTThe same entry. The address it binds to.0.0.0.0Restart

Logging

The logger in @scayle/storefront reads these when the first logger is created. See Format and levels and Redaction.

VariableWhat it doesDefaultChange needs
STOREFRONT_LOG_FORMATpretty for readable lines. Any other value writes JSON.jsonRestart
STOREFRONT_LOG_LEVELThe minimum level: debug, info, warn, or error. Any other value falls back to info.infoRestart
STOREFRONT_LOG_REDACT_KEYSComma-separated keys to redact, merged with the built-in list.UnsetRestart

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.

VariableWhat it doesDefaultChange needs
STOREFRONT_CACHE_DISABLEDtrue turns the data cache off: getOrSet runs its fetcher every time and stores nothing. The response cache headers don't change.OffRestart
STOREFRONT_CACHE_COMPRESSIONCompression of stored values: brotli, gzip, deflate, or none. Sessions share the store, so changing it on a live shop can leave existing sessions unreadable.brotliRestart
STOREFRONT_KV_DISABLE_CLUSTER_MODEtrue 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 runsRestart
SCAYLE_KV_HOSTHost of SCAYLE KV, or of your Redis or Valkey instance.localhostRestart
SCAYLE_KV_PORTIts port.6379Restart
SCAYLE_KV_USER, SCAYLE_KV_PASSWORDIts credentials.UnsetRestart
SCAYLE_KV_TLStrue connects over TLS.OffRestart
SCAYLE_KV_BASEA prefix for every key the store writes.UnsetRestart

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.

VariableWhat it doesDefaultChange 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 prefixRebuild
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 sentRebuild
ANALYZE_BUNDLEvite.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.UnsetRebuild

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.

VariableWhat it doesDefaultChange needs
HTTPS_CERT, HTTPS_KEYvite.config.ts. Paths to the TLS certificate and key of the dev server.certs/localhost.crt, certs/localhost.keyRestart
STOREFRONT_DETECTED_COUNTRYCountryService in @scayle/storefront. Stands in for the CF-IPCountry header that country detection reads. A production build ignores it. See Country Detection.UnsetRestart