Manage Oxygen environments and variables

A Hydrogen storefront on Oxygen has one or more environments. Each environment has its own environment variables and, except preview, links to a branch in your app's Git repository and has its own URL. Every deployment belongs to one environment.

Anchor to How it worksHow it works

Oxygen assigns each deployment to an environment based on the branch that it was deployed from:

Each environment except preview has a generated URL that points to its most recent deployment. You can roll back an environment to point to an earlier deployment.

Oxygen passes the environment's variables to your Worker's env argument on every request. Deployments are immutable, so a deployment keeps the variable values that it had when it was deployed. If you change a variable, then redeploy the environments that use it.

Anchor to Manage environmentsManage environments

The production and preview environments are required, and you can't delete them. Create custom environments to test features or share work in progress without changing production.

Anchor to Create an environmentCreate an 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 environment. The branch 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. Change the production environment's branch or visibility, or a custom environment's name or visibility.
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.
5. Click Delete to confirm.

Anchor to Environment visibilityEnvironment visibility

Environments are private by default, which means that you need to be logged in to your store to view them. A public environment is visible to anyone who has its URL.

Private environment URLs load more slowly, because Oxygen verifies authentication on each request.

Anchor to Make an environment public or privateMake an environment 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 Public or Private.
5. Click Save.

Anchor to Public environment limitsPublic environment limits

The number of public environments that a store can have depends on its plan:

Retail, nonprofit, and custom plans also include one public environment.

Anchor to Environment variablesEnvironment variables

Environment variables are key-value pairs. Each environment can have up to 110 variables, and a variable can have a different value in each environment.

Anchor to Variables that Shopify setsVariables that Shopify sets

When you create a storefront, Shopify adds the variables that your app needs to query your store. Some are read-only, so you can't edit them directly.

Without PRIVATE_STOREFRONT_API_TOKEN, the React Router template reads from mock.shop. Set MOCK_SHOP=1 to force mock.shop in an environment that has a token.

Anchor to Read variables in your appRead variables in your app

Oxygen passes variables to your Worker as the env argument, not as process.env. The React Router template stores env in the router context in server.ts, so loaders, actions, and middleware read it from there:

When you add a variable, also add it to the Env type in app/lib/env.ts. Read secrets in server code only, and don't return them from a loader.

To use your storefront's variables locally, run npx shopify hydrogen env pull. It writes them to your .env file, and MiniOxygen passes them to your Worker's env argument.

Anchor to Create a variableCreate a variable

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Under Custom variables, click Add variable.
4. Under Key, type a key, such as EXAMPLE_API_TOKEN.
5. Under Value, type the value.
6. Optional: To hide the value after you save it, check Make this value secret.
7. Under Environments, select the environments that get the value.
8. Click Save.

To set a different value for other environments, click Add another value.

Anchor to Edit a variableEdit a variable

1. In your Hydrogen storefront, click Storefront settings.
2. Click Environments and variables.
3. Click the variable to edit.
4. Change its key, values, or environments.
5. Click Save.

After you save, the Shopify admin offers to redeploy the environments that use the variable. Existing deployments keep the old value until you redeploy.

Anchor to Delete a variableDelete a variable

Deleting a variable deletes its key and all its values.

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

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

If your private Storefront API token is exposed, then rotate it:

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: Update any other apps that use the token.
6. Deploy your storefront again. Oxygen doesn't redeploy environments when you rotate a token.
7. Beside the Old token, click Revoke, and then click Delete token.

Anchor to Next stepsNext steps

Manage deployments

Deploy continuously, share previews, redeploy, and roll back.

Customer accounts

Use the customer account variables to log customers in.