Environment Variables

Use environment variables to manage configuration values for your Storefront Next storefront without making code changes. They’re stored securely outside your codebase, making them ideal for API keys for third-party integrations, feature flags for application logic, and configuration that differs between environments such as development, staging, and production. Environment variables are accessible in your app server code only and aren’t available to edge services.

Prerequisites

You must have a developer or admin role on the project for which you’re managing environment variables. If you don’t have access, ask a Managed Runtime admin for access.

Environment Variable Types

Storefront Next uses a naming convention to control where a variable is available.

PUBLIC__ prefix: Variables with this prefix are safe to expose to the browser. They’re automatically merged into the app configuration at run time and available in both server and client code via getConfig() and useConfig(). Use these for client IDs, feature flags, public API endpoints, and other non-sensitive values.
No prefix: Variables without the PUBLIC__ prefix are server-only. They’re never bundled into client JavaScript. Use these for secrets, API credentials, and private tokens. Read them directly from process.env in server-side code such as loaders, actions, and middleware.

The PUBLIC__ Path Syntax

Use the double underscore (__) in PUBLIC__ variable names to target nested configuration paths. This path syntax maps directly to dot notation in your config object.

For example, this environment variable:

1PUBLIC__app__myFeature__apiEndpoint=https://api.example.com

Maps to this config path:

1config.app.myFeature.apiEndpoint

Values are automatically parsed to the correct type:

1PUBLIC__app__myFeature__count=42 # → number
2PUBLIC__app__myFeature__enabled=true # → boolean
3PUBLIC__app__myFeature__items=["a","b"] # → array
4PUBLIC__app__myFeature__data='{"x":1}' # → object
5PUBLIC__app__myFeature__name=hello # → string

For complex nested values, set an entire object at once using JSON:

1PUBLIC__app__pages__cart='{"quantityUpdateDebounce":1000,"maxQuantityPerItem":500}'

When you set environment variables in Runtime Admin, use single-line JSON without surrounding quotes.

Manage Environment Variables in Runtime Admin

Manage environment variables in the UI in Runtime Admin.

Use Runtime Admin

To create, update, remove, or view environment variables:

If you created your storefront in Business Manager, access your environment variables from the storefront page.

a. In Business Manager, click App Launcher and then select Administration > Sites > Storefronts, and then click your storefront.

b. In the storefront detail page, click the environment, and then click Manage next to Environment Variables. You’re redirected to the Environment Variables page in Managed Runtime in a new tab.
Alternatively, access your storefront from Managed Runtime.

a. Log in to Runtime Admin.

b. Go to a project’s Overview page.

c. Click the name of the environment.

d. Click Environment Variables in the left navigation.

When you add a new environment variable, wait for the redeploy of the bundle to complete, and then deploy a new bundle that uses the new variable.

Also, you can manage environment variables via the CLI or API. See Automate Environment Variable Management with the CLI or API.

Note

Best Practices

Choose clear, descriptive names for your environment variables.
Avoid hardcoding sensitive information such as API keys in your code. Use environment variables to keep them secure.
Don’t pass environment variables into data that will be serialized to the page. Consider adding a test to make sure you’re not leaking environment variable data.
Never store secrets or private keys in PUBLIC__ variables. The’re exposed to the browser.
Read server-only secrets directly from process.env. Never pass them through the config system.
Test variable changes locally and in a non-production environment before applying them to production. Testing in stages helps resolve issues early, simulate site behavior, validate functionality, and run user acceptance testing before deploying to production.
Add error handling in your code for cases where a variable might be undefined.
Don’t return environment variables from loader functions or react-query hooks.
Use environment variables only server-side. By default, environment variables aren’t exposed client-side. To expose them client-side (for example, in your configuration file), make sure that exposing the values complies with your security practices.
Control access to the environment variables to prevent unauthorized modifications.
Document the purpose and configuration of each environment variable. This helps in onboarding new developers and troubleshooting issues.
Restart your dev server after changing .env files. Environment variables load at startup.

Constraints

Environment variables are subject to these constraints.

Each environment has a limit of 100 environment variables.
Environment variable names can contain only alphanumeric characters, underscores ( _ ), and dashes ( - ).
Environment variable names must be 512 characters or less, and cannot start with reserved prefixes: AWS, MRT, X_MRT, MOBIFY, X_MOBIFY, SSR_PROXY, NODE.
Environment variable names cannot use any reserved names: BUNDLE_ID, DEPLOY_ID, DEPLOY_TARGET, EXTERNAL_DOMAIN_NAME, HANDLER, LAMBDA_RUNTIME_DIR, LAMBDA_TASK_ROOT, NODE_ENV, REDIRECT_BUCKET, REDIRECT_KEY, REDIRECT_UPDATE, REMOTE, X_AMZN_TRACE_ID.
Environment variable values must be strings. To store complex values, encode JSON into a string.
The maximum size of the values of environment variables set for an environment is 32 KB.
Paths used in PUBLIC__ variable names must already exist in config.server.ts. Variables that reference undefined paths are rejected at startup.