Environments

Hydrogen storefronts can contain multiple environments, to which you make deployments.

Each environment is linked to a branch in your Hydrogen app’s Git repository:

Each environment can have its own set of environment variables, which allows you to use different values in your app depending on the environment. This can be useful for testing, feature development, and security.

Anchor to Managing environmentsManaging environments

The production and preview environments are required for all storefronts, and can't be deleted. In addition to these required environments, you can optionally create additional custom environments to develop new features, test out ideas, and more.

Anchor to Create a new environmentCreate a new environment

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click Add environment.
4. Select an existing repository branch to link to the environment, or create a new branch.
5. Type a name for the branch. The name determines the environment URL.
6. Select whether to make the environment public or private.
7. Optional: Under Copy environment variables, select an existing environment to copy variables from.
8. Click Save.

Anchor to Update an environmentUpdate an environment

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click the environment to edit.
4. Make your changes.
5. Click Save.

Anchor to Delete a custom environmentDelete a custom environment

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click the environment to delete.
4. Click Delete environment.

Anchor to Environment variablesEnvironment variables

Each environment can have its own set of environment variables, which are key-value pairs. Variable keys can be called in your app code, and return contexual values for the environment where the deployment is running. Each environment can have a maximum of 110 unique environment variables.

Anchor to Accessing environment variable values in your appAccessing environment variable values in your app

Hydrogen automatically adds your environment variables to a request's context object. You can access the values of environment variables from a loader or action:

Anchor to Create a new environment variableCreate a new environment variable

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Under Variables, click Add variable.
4. Under Key, type a key. It's a common convention for keys to use all-capital letters and underscores, such as EXAMPLE_API_TOKEN.
5. Under Value, add the value.
6. Optional: Check Make this value secret to hide the value after saving. This can be useful for sensitive information like API keys.
7. Under Environments, select the environments where the value should be returned.
8. Click Save.

Click Add another value to add additional values for other environments.

Anchor to Edit an environment variableEdit an environment variable

You can edit keys and values, as well as which environments they apply to.

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click the environment variable to update.
4. Make your changes.
5. Click Save.

You might want to redeploy any environments that require the updated variables.

Anchor to Delete an environment variableDelete an environment variable

Deleting an environment variable deletes the key and all its associated values.

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click the environment variable to delete.
4. Click Delete variable.
5. Click Delete variable to confirm.

Anchor to Required environment variablesRequired environment variables

Oxygen requires the following variables to query your store's data. They're automatically added when you create a storefront. Some variables are read-only, meaning they can’t be edited directly.

Anchor to Rotate your private Storefront API tokenRotate your private Storefront API token

If your private Storefront API access token is exposed publicly, then you should rotate it to protect sensitive data and prevent abuse.

1. In your Hydrogen storefront, click Storefront settings.
2. Click Storefront API
3. Under Rotate private access token, click Generate new token
4. Click Generate new token to confirm.
5. Optional: If you have other client apps using your private API token, then update them with the new token value.
6. Under Past private access token, click Delete.
7. Push a commit to your GitHub repo to trigger a new deployment. At this time, Oxygen doesn't automatically re-deploy environments when rotating API tokens.

Anchor to ImmutabilityImmutability

Oxygen deployments are immutable, which includes their environment variable values. This means any changes to environment variables don’t affect deployments that were made in the past.

If you create or update environment variables, then you need to redeploy before your changes will take effect.

Anchor to Environment visibilityEnvironment visibility

By default, environments are private, which means that you need to be logged into your store to view them. You can also make an environment public, meaning anyone with the URL can view it.

Anchor to Toggle an environment to public or privateToggle an environment to public or private

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click the environment to edit.
4. Under URL privacy, select either Public or Private.
5. Click Save.

Anchor to Public environment limitsPublic environment limits

Stores have a limited number of public environments available, based on their plan.

Anchor to Environment URLsEnvironment URLs

Each environment has an automatically generated URL. By default, this URL always points to the most recent deployment to that environment.

Anchor to Next stepsNext steps

• Learn how to deploy your Hydrogen storefront to Oxygen and other runtimes.