docs

Configuration

What goes in storefront.config.ts, and when does a change take effect? The file holds every value that differs between shops or between countries: your tenant space and shop, the credentials your server uses, the countries you serve, the routes the response cache may store, and the fields your own code adds. Literal values in the file are compiled into the server bundle, so changing one takes a rebuild. Values the file reads from process.env are evaluated when the server starts, so changing one takes a restart.

@scayle/storefront validates the result when the server starts and refuses to boot on an invalid config. Only an allowlisted part of it ever reaches the browser. Environment Variables lists the variables the Storefront Application V3 reads and links to the feature pages that list their own.

What goes in the file

storefront.config.ts sits at the project root and default-exports a call to defineStorefrontConfig from @scayle/storefront/config. The function returns its argument unchanged. It exists for the types, so your editor checks the object against StorefrontConfig while you type.

The schema is deliberately narrow: it only has fields for values that vary per shop or per country. A value every shop would set the same way is a constant in the code that uses it. What your own code needs goes under publicFields and privateFields, which you extend with your own types. Config fields lists every field.

Two topics have their own pages: Caching covers cacheableRoutes, and Routing and Countries covers countrySelector, countries, and the top-level domain.

Build time and runtime

Vite compiles storefront.config.ts into the server bundle when you build, but it doesn't run the file. storefrontConfigPlugin from @scayle/storefront-build exposes it as the virtual module virtual:storefront-config, which @scayle/storefront imports. The literals are compiled in, and the process.env reads stay in the bundle as code. They run when the server starts and the module evaluates.

At build time storefrontConfigPlugin compiles storefront.config.ts into virtual:storefront-config in .output/server. At server start the module evaluates with process.env reads, and @scayle/storefront validates the result into config.

A change therefore takes effect at one of two points:

You changeIt takes effect after
A literal in storefront.config.ts, such as a country's path or a route's TTLA rebuild and redeploy
A variable that storefront.config.ts reads, such as STOREFRONT_API_KEYA restart
A variable another server module reads, such as STOREFRONT_LOG_LEVELA restart
A variable Vite reads during the build, such as CMS_PROVIDERA rebuild and redeploy

The split lets one build run everywhere. You build once and run the same output in staging and production with different variables, and the secret values never become part of the build output. It also means that editing the file on a server does nothing: storefront.config.ts doesn't ship in .output/, only its compiled copy does.

Where the variables come from depends on how you run the server. Under pnpm dev, storefrontConfigPlugin loads your .env file into process.env before the config evaluates, and a variable already set in your shell wins over the file. In production, nothing reads .env: the variables come from your container or hosting environment.

Validation at startup

@scayle/storefront validates the config once, when the server starts, and every request then reads the validated object. A config that fails throws at that point, so the process stops before it serves a request, and the error names the field. Validation runs in two steps:

  1. A Zod schema checks each field's type and format, such as a locale like de-DE or a session secret of at least 32 characters. The schema is a discriminated union on countrySelector, so the selector decides whether every country needs a path or a domain.
  2. Cross-field rules that the schema can't express: at most one country sets isDefault, path_except_default needs one that does, and no two countries share a shopCountryId.

Three things fall outside these checks:

  • The ! after a process.env read only silences TypeScript. An unset variable arrives as undefined and fails the schema, but an empty one passes for storefrontApiKey and the three checkout values, which accept any string.
  • Your own fields aren't checked. The schema declares publicFields and privateFields as empty objects and keeps whatever you put in them. Add your own config field shows how to validate them yourself.
  • CMS credentials aren't part of the config. parseCmsEnv() checks them separately when src/server/index.ts loads, so a missing credential stops the boot as well.

Your server code reads the validated object as ctx.get('config') in middleware, as this.storefront.config in a controller, or as config imported from @scayle/storefront at module level.

What reaches the browser

The config holds your Storefront API key, the OAuth client secret, the session secret, and every country's checkout credentials, so the object itself never leaves the server. The browser gets an allowlisted copy instead. The Inertia middleware in @scayle/storefront builds the shared storefront prop field by field, so a field reaches the browser only when it's on this list or under publicFields:

Reaches the browserStays on the server
ShoptenantSpace, shopKey, countrySelector, oauth.clientId, version, publicFieldsstorefrontApiKey, oauth.clientSecret, session, domain, cacheableRoutes, sitemaps, clientIpHeader, privateFields
Active countryname, locale, countryCode, currency, shopCountryId, isDefault, path or domain, publicFieldscheckout, privateFields

Instead of the top-level domain, the browser receives the public origin the server resolved for the request, as storefront.origin. Shared props are embedded in the HTML of a first page load and sent with every Inertia visit, so treat anything under publicFields as published.

That gives your own values two homes. A value the browser needs, such as a tag manager ID, goes under publicFields. A value only the server may see, such as an API key, goes under privateFields, which no part of the SDK copies to the browser.

Environment variables follow the same line. Vite exposes only VITE_* variables to client code, through import.meta.env, and inlines their values into the browser bundle when you build. Vite never inlines a STOREFRONT_* variable, so one reaches the browser only when storefront.config.ts copies it into publicFields, as it does with STOREFRONT_GTM_ID. Don't add STOREFRONT_ to envPrefix in vite.config.ts: Vite would then inline every variable with that prefix, secrets included, into client JavaScript.

Storage backend

Sessions need a reachable storage backend in every environment. The same store also holds the cached Storefront API and CMS responses, see Caching.

Local development uses the Redis container from the docker-compose.yml in your project root. Set Up Your Storefront shows how to start it. A plain Redis is a single instance, so set STOREFRONT_KV_DISABLE_CLUSTER_MODE to true, see Cache and SCAYLE KV.

Production uses SCAYLE KV on Storefront Hosting, which the application connects to in cluster mode. The server starts without a reachable store, because the connection opens on the first read or write. Requests that read or write a session then fail.

Common tasks

Change a value per environment

Read the value from process.env in storefront.config.ts, then set the variable in every environment: in .env for local development, and in the container or hosting settings of each deployment. A restart applies a new value. The shipped file shows the patterns for each kind of value:

Every variable arrives as a string, so convert numbers and booleans yourself. For an optional field, map an empty variable to undefined the way the domain line does. An empty string is still a value, and domain rejects it as an invalid host, while undefined leaves the field unset.

Name a new variable by the naming conventions.

Add your own config field

Your shop needs a setting that the schema doesn't have. Pick the interface by where the value applies and who may read it:

Shop-widePer country
The browser and the serverPublicConfigFieldsPublicCountryFields
The server onlyPrivateConfigFieldsPrivateCountryFields

All four start out empty, and @scayle/storefront/config exports them for you to extend. Add your field in the declare module block at the top of storefront.config.ts, where the application already declares its own, then set the value. Since the schema doesn't check your fields, parse the value in the same file, so a bad one stops the boot like a schema error. This example adds a return period per country:

A field you declare without ? is required in every publicFields object you write, so TypeScript reports a country that leaves it out. Server code reads the value from the active country, as this.storefront.country.publicFields?.returnPeriodDays in a controller. publicFields is optional on the type, which is why the read needs ?..

Add the variable to the test.env block in vitest.config.ts as well. Server tests load the real storefront.config.ts, so a variable that's missing there fails them on import.

Expose a value to the browser

Declare the value on PublicConfigFields or PublicCountryFields and set it under publicFields, as in Add your own config field. A component then reads it through useStorefrontConfig():

config is the whole shared storefront prop, which is why a shop-wide value sits one level down, under config.value.config. country is the active country. SFAnalyticsHead.vue reads gtmId the same way.

Don't hand this.storefront.config or a country entry to a page yourself, as a page prop or as shared data. Both carry the secrets listed in What reaches the browser, so copy only the fields the page needs.

Configure a third-party API

Your shop calls a service the SDK doesn't know, such as the review provider from Add a custom service. Split its settings by who may see them: a public key or app ID that the browser needs goes under publicFields, and the URL and API key the server calls it with go under privateFields.

Add a custom service shows the service reading them from the context it receives. The parse in storefront.config.ts guarantees that both values exist once the server is running, which is what makes the ! there safe. privateFields never reaches the browser, so the key stays on the server unless your own code returns it, for example in a page prop or an oRPC response.

Config fields

Top-level fields

FieldTypeRequiredDescription
tenantSpacestringYesYour tenant space. The SDK builds the SCAYLE Storefront API host from it, as <tenantSpace>.storefront.api.scayle.cloud.
shopKeystringYesYour parent shop key, from SCAYLE Panel ➜ Shops.
storefrontApiKeystringYesToken for the SCAYLE Storefront API.
oauth{ clientId, clientSecret }YesClient credentials for the SCAYLE Authentication API. Only clientId reaches the browser.
session{ secret, ttl?, cookieName? }Yessecret signs the session cookie and needs at least 32 characters. ttl is in seconds and defaults to 30 days. The cookie is named <shopCountryId>-<cookieName>, and cookieName defaults to session. See Session.
countrySelector'path', 'path_except_default', 'domain'YesHow a URL names its country, and which country fields the schema requires. See Choosing a country selector.
countriesarrayYesOne entry per shop country. See Country fields.
domainstringNoPath selectors only. The public host for absolute URLs, as a bare host without a scheme. Unset uses the request host. See Public origin.
cacheableRoutesRecord<string, number>NoResponse cache TTL in seconds, keyed by Hono route pattern. See Caching.
publicFieldsPublicConfigFieldsNoYour shop-wide fields that the browser may read.
privateFieldsPrivateConfigFieldsNoYour shop-wide fields that stay on the server.
versionstringNoYour release version, sent as shop_version on SCAYLE Analytics events. The Storefront Application passes the version from package.json.
clientIpHeaderstringNoRequest header that holds the user IP for request.originalIp. Unset uses X-Forwarded-For.
sitemaps{ bucket, region }NoS3 bucket and AWS region of the Robots and Sitemaps add-on. When set, the server answers /robots.txt and the sitemaps from that bucket.

Country fields

Each entry in countries:

FieldTypeRequiredDescription
namestringYesDisplay name.
localestringYesLanguage and region, such as de-DE or en-US: two to four lowercase letters, a hyphen, and two to four uppercase letters.
countryCodestringYesTwo uppercase letters, ISO 3166-1 alpha-2.
currency{ currencyCode, fractionDigits?, display? }YescurrencyCode is the ISO 4217 code, such as EUR. fractionDigits caps the fraction digits of formatted prices. display is symbol (the default), narrowSymbol, code, or name.
shopCountryIdnumberYesShop country ID from the SCAYLE Panel. A positive integer, unique across countries.
checkout{ user, token, secret }YesSCAYLE Checkout credentials for this shop country. Never reaches the browser.
isDefaultbooleanNoMarks the default country. At most one country sets it, and path_except_default requires one.
pathstringPath selectors onlyURL prefix, such as de.
domainstringDomain selector onlyHost of this country, as a bare host such as example.de.
publicFieldsPublicCountryFieldsNoYour per-country fields that the browser may read.
privateFieldsPrivateCountryFieldsNoYour per-country fields that stay on the server.