Project Configuration
Storefront Next uses a centralized, type-safe configuration system that gives you:
- IDE autocomplete: Full TypeScript support with suggestions as you type.
- Environment overrides: Customize settings per environment without code changes.
- Validation: Catch configuration errors at startup, not at run time.
- Security by design: Clear separation between public and server-only values.
All configuration lives in a single file (config.server.ts) with defaults that you can override by using environment variables.
Storefront Next provides two APIs for accessing configuration.
The main configuration file is config.server.ts in your project root.
For descriptions of the configuration options, see Configuration Options Reference in the storefront-next-template GitHub repo.
The configuration is organized into three main sections.
| Section | Purpose | Client Access |
|---|---|---|
metadata | Project name and slug for deployment | Server only |
runtime | SSR and deployment settings | Server only |
app | Application settings (commerce, features, UI) | Server and client |
The app section is automatically made available to client-side code. The metadata and runtime sections remain server-only.
The runtime.ssrOnly option accepts an array of glob patterns for files that must be available on the server but aren’t publicly accessible from the client. Use this option for server-side resources that aren’t exposed via public URLs.
Don’t import config.server.ts directly in your app code. While the .server.ts suffix prevents the file from being bundled into client-side code (a React Router framework feature), always use getConfig() or useConfig() to access configuration values. These APIs ensure that the configuration is properly loaded and available in the correct context.
To start the storefront, set B2C Commerce API credentials in a .env file at your project root. All the other settings have a working default in config.server.ts. Declare them only if you want to override their values.
The Storefront Next template includes an .env.default file pre-filled with public demo credentials. Copy it to .env to get started.
A public SLAS client needs three variables. These values are safe to expose to the browser, so they use the PUBLIC__ prefix.
This table describes each variable.
| Variable | Purpose |
|---|---|
PUBLIC__app__commerce__api__clientId | SLAS client ID provisioned in B2C Commerce |
PUBLIC__app__commerce__api__organizationId | B2C Commerce organization or realm ID (for example, f_ecom_zzrf_001) |
PUBLIC__app__commerce__api__shortCode | SCAPI short code for your tenant (for example, kv7kzm78) |
A private SLAS client uses the same three variables, plus a feature flag that switches authentication into private-client mode and a server-only secret that signs token requests.
Don’t add COMMERCE_API_SLAS_SECRET to config.server.ts and don’t give it a PUBLIC__ prefix. Read it directly from process.env in server-side code, such as loaders, actions, and middleware. Anything with the PUBLIC__ prefix is bundled into the browser-visible JavaScript.
For SLAS private client setup in B2C Commerce, see Authorization for Shopper APIs.
To deploy your storefront to Managed Runtime, also set the deployment variables that the Storefront Next CLI reads. See Storefront Next CLI.
Every other setting has a working default in config.server.ts. To override one, use a PUBLIC__ environment variable with the path syntax described in Environment Variable Overrides.
For feature-specific configuration, see the dedicated guides.
- Configure Multisite URLs — sites, locales, currencies, and URL patterns
- Set Up Hybrid Proxy Locally —
HYBRID_PROXY_*,SFCC_ORIGIN, routing rules - Passwordless Login for Storefront Next — passwordless login, OTP request, and reset password modes
- Shopper Context — qualifier-based personalization
- Shopping Agent for Storefront Next — embedded chat configuration
Override any configuration value by using environment variables with the PUBLIC__ prefix. With environment variables, you can customize settings per environment (development, staging, production) without modifying code.
Use double underscores (__) to navigate nested configuration paths.
Values are automatically parsed to match the expected type.
You can also set entire nested objects using JSON.
Path matching is case-insensitive, so all these variables work.
Environment variables are deep merged into the defaults from config.server.ts. Only the values you specify are overridden. Everything else keeps its default.
The PUBLIC__ prefix indicates values that are safe to expose to the browser. These values are bundled into client-side JavaScript.
Don’t use PUBLIC__ for secrets, API keys, passwords, or authentication tokens. These values are visible to anyone who uses your site.
Use PUBLIC__ For | Use Non-Prefixed For |
|---|---|
| Client IDs | API secrets |
| Site IDs | Private keys |
| Locales and currencies | Database credentials |
| Feature flags | Authentication tokens |
| Public API endpoints | SLAS secrets |
For server-only secrets, use environment variables without the PUBLIC__ prefix and read them directly from process.env.
Use getConfig() with the router context.
Use the useConfig() hook:
Client loaders don’t have access to router context. Call getConfig() without arguments.
To add a new configuration value, follow these steps.
Add the type definition in src/config/schema.ts:
Add the default in config.server.ts:
No code changes needed. Use the PUBLIC__ prefix.
When deploying to Managed Runtime (MRT), set your environment variables in the Runtime Admin.
- Log in to the Runtime Admin.
- Navigate to your project → Environment Variables.
- Add the required
PUBLIC__variables. - Add any server-only secrets without the
PUBLIC__prefix. - Deploy your app.
MRT has limits: variable names max 512 characters, total PUBLIC__ values max 32 KB. Use JSON to consolidate related settings if needed.
Restart your dev server. Environment variables are loaded at startup.
- Verify the variable name starts with
PUBLIC__(double underscore after PUBLIC) - Check the
.envfile is in the project root - Ensure that the path exists in
config.server.ts—you can only override existing paths
Update both src/config/schema.ts (types) and config.server.ts (defaults) to match.
Copy .env.default to .env and set the required B2C Commerce credentials. See Minimum Required Configuration.
The configuration system validates that environment variable paths exist in your config. If you see an error like "local" doesn't exist, check for typos. The system suggests similar valid paths when possible.