Environment Variables

Environment variables allow you to add variables into the application process running in an environment, without having to make code changes. Environment variables are stored securely, making them ideal for use cases such as:

  • API keys for third-party integrations
  • Feature flags for application logic
  • Configuration that differs between environments or that might not be secret

Environment variables are only accessible in the app server. They can't modify the behavior of edge services including proxies and edge functions.

Follow these tutorials to set environment variables then implement code in your PWA Kit site to use the variables. You can customize the code according to your specific requirements. The tutorials show you how to:

We recommend testing the steps on your local machine, then in a non-production environment before deploying your changes to production. For more guidance, see Best Practices, Troubleshoot Environment Variables, and Debugging Locally.

Environment variables:

When you introduce a new environment variable, first set it via API or Runtime Admin. Wait until redeploy completes and then deploy a new bundle that uses it.

Set, Update, and Unset Environment Variables

Use projects_target_env_var_partial_update:

To unset an existing environment variable, set its value to null.

Modifying environment variables redeploys the environment. The updated values are available when the deploy completes.

Get all Environment Variables

Use projects_target_env_var_list:

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

  1. Log into Runtime Admin. To get access to Runtime Admin, see Managed Runtime Administration.
  2. Go to a project’s Overview page.
  3. Click the name of the environment for which you want to manage environment variables.
  4. Click Environment Variables in the left navigation.
  • Choose environment variable names that make sense for your app. Use descriptive names: Choose clear and concise names for your environment variables to make them easily understandable for your team.
  • Avoid hardcoding sensitive information like 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.
  • Don't return environment variables from getProps or react-query hooks.
  • Use environment variables only server-side. By default, environment variables aren’t exposed client-side. You can choose to expose them client-side (for example, in your configuration file), but make sure that exposing the values complies with your security practices.
  • Test your environment variables on your local machine, then in a non-production environment before deploying them to production. This helps to ensure that you can quickly resolve issues locally, then simulate site behavior, validate functionality, and do any user acceptance testing before deploying to production.
  • Include error handling in your code that uses environment variables to prevent failures due to undefined environment variables.
  • 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.

The usage of environment variables is subject to the following 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.

This section provides suggested solutions for common errors that you might encounter while using environment variables.

Your code throws an Error stating that a variable is missing.

Cause: The environment variable that the code calls isn’t set.

Suggested Solution: Call the projects_target_env_var_partial_update API endpoint to set the applicable environment variable.

Your code logs an error message stating that the environment variable wasn’t found.

Cause: The code couldn’t find the environment variable because there’s a typo in the code or an incorrect environment variable name is used.

Suggested Solution: Confirm that you spelled the environment variable name correctly in your code and you used the desired environment variable name. Check the environment variable name by calling the projects_target_env_var_list API endpoint to see the full list of variables that are set.

Your API call to set an environment variable fails.

Cause: The environment variable name might not comply with the constraints. For example, the size of the value of an environment variable is over 32 KB.

Suggested Solution: Confirm that your environment variable complies with the constraints.

Authentication errors occur when you execute code that involves using an API key.

Cause: The API key that you used when you set the environment variable is not in the expected format or is missing.

Suggested Solution: Confirm that the API key stored by an environment variable is correct. If needed, call the projects_target_env_var_partial_update API endpoint to correct the API key.

A fetch request fails with a network error.

Cause: A URL for any API endpoint called in your code might not have been correctly defined or is invalid. For example, the URL for a content management system (CMS) endpoint is incorrect.

Suggested Solution: Confirm that any URLs for API endpoints in your code are correct.