--- schema_version: "1" id: e55f8333a6edb79938f3133401dd70f9ed774df1c03ca7cbbc287da713659ecb title: Environment Variables collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-environment-vars.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.html source_site: developer.salesforce.com content_type: documentation content_hash: f468b372afbbde1aa001760911a70afcf2ff99bf4f5bea6b0dceeb82514b18dd products: - Composable Storefront - Salesforce APIs --- # 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, secrets, 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. On Managed Runtime, environment variables are injected into the server process at startup and are accessible to server-side code through `process.env`. ## 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. - For the Developer Workspace (Beta), you must have the "Storefront Environment Variables" permission for a specific storefront with the appropriate read, write, and delete rights. ## 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: ```Bash PUBLIC__app__myFeature__apiEndpoint=https://api.example.com ``` Maps to this config path: ```Bash config.app.myFeature.apiEndpoint ``` Values are automatically parsed to the correct type: ```Bash PUBLIC__app__myFeature__count=42 # → number PUBLIC__app__myFeature__enabled=true # → boolean PUBLIC__app__myFeature__items=["a","b"] # → array PUBLIC__app__myFeature__data='{"x":1}' # → object PUBLIC__app__myFeature__name=hello # → string ``` For complex nested values, set an entire object at once using JSON: ```Bash PUBLIC__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 Business Manager (Beta) 1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Storefronts**, and then click your storefront. 2. Depending on which environment you want to access, under Primary Environment or Additional Environments, click the dropdown arrow and select **Environment Settings**. 3. Click **Environment Variables**. 4. Add, edit, or delete an environment variable on this page. ## 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: 1. If you created your storefront in Business Manager, access your environment variables from the storefront page. a. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) 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. 2. Alternatively, access your storefront from Managed Runtime. a. Log in to [Runtime Admin](https://runtime.commercecloud.com). 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. **note:** Also, you can manage environment variables via the CLI or API. See [Automate Environment Variable Management with the CLI or API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-cli.md). ## Manage Environment Variables in Business Manager (Beta) In the Developer Workspace (Beta), access and managed environment variables from the Storefront Settings page. ### View and Manage Environment Variables 1. In Business Manager, go to **Administration > Sites > Storefronts > _Your Storefront_**. 2. Next to an environment, click the dropdown arrow and select **Environment Settings**. 3. Click **Environment Variables**. The page lists all variables defined for the environment, including the variable name and whether the value is visible or masked. To add an environment variable from the Environment Variables page, click **New Environment Variable**. To edit or delete an environment variable, select it and then update or delete it. **warning:** Deleting an environment variable takes effect on the next deployment. If your storefront code references the deleted variable, the behavior at run time depends on how your code handles a missing value. ## 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. ## See Also - [Troubleshoot Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-env-var-troubleshoot.md) - [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md)