Storefronts
A Hydrogen storefront is associated with a Hydrogen Git repository, which contains different versions of the storefront that are associated with Git branches. You can connect multiple storefronts or stores to a Hydrogen Git repository.
This guide discusses how storefronts work and describes how environments, deployments, environment variables, and preview URLs can be used to manage and preview your Oxygen deployments.
How it works
Anchor link to section titled "How it works"Hydrogen storefront code exists in a Git repository. When commits are pushed to the Git repository that's connected in the Hydrogen channel, the storefront code is built into a Hydrogen app and deployed to Oxygen.
If the Git repository doesn't have the required files and directories for deploying the storefront code to Oxygen, then Shopify creates a new branch called add-oxygen-workflow
, and then creates a new pull request in the Git repository. After the new branch and the pull request are created, you're prompted to approve and merge the pull request, so that you can start using the Hydrogen channel.
Environments
Anchor link to section titled "Environments"You can create different versions of a Hydrogen storefront without affecting other versions of a storefront. We call these versions "environments". Each environment contains deployments and preview URLs that enable you to preview commits that are deployed to the environment. You can also add environment variables to an environment or import environment variables from other environments to store reusable data that can be used in the Hydrogen storefront code.
Oxygen provides the following types of environments:
Production environment
Anchor link to section titled "Production environment"The production environment contains the state of a Hydrogen storefront that's built on the default branch of the Git repository that's connected to the Hydrogen channel.
The production environment has an environment URL and deployment URLs.
Custom environments
Anchor link to section titled "Custom environments"Custom environments are environments that have a name, and contain the state of a Hydrogen storefront that's built from a branch that's assigned to a custom environment.
Each custom environment has an environment URL and deployment URLs.
The environment URL is named after the branch name. If you change the branch name, then the environment URL changes.
Preview environment
Anchor link to section titled "Preview environment"The preview environment contains deployments that provide previews of the latest commits to any branch that isn't assigned to a custom environment.
The preview environment has deployment URLs, but doesn't have an environment URL.
Public environment limits
Anchor link to section titled "Public environment limits"The active plan on the shop determines how many public environments can be enabled in the Hydrogen channel. The following table describes the public environment limit for each plan in which Oxygen is available:
Plan | Public environment limit |
---|---|
Basic | 1 |
Shopify | 1 |
Advanced | 1 |
Shopify Plus | 25 |
Plus Partner Sandbox stores | 1 |
Deployments
Anchor link to section titled "Deployments"A deployment is a snapshot of your built Hydrogen storefront after it's been uploaded to an Oxygen environment. Oxygen deployments are triggered when a Git commit is pushed to a Git repository that's connected to a Hydrogen storefront in the Hydrogen channel. Each deployment has a preview URL that provides a preview of the storefront in a specific Git commit.
The following diagram shows how Git branches might be connected and deploy to each type of environment:

Production deployments
Anchor link to section titled "Production deployments"A deployment in the production environment is triggered when a Git commit is pushed to the default branch of a Git repository that's connected to a storefront in the Hydrogen channel. You can access previous deployments by clicking the N more deployments in Production link, where N is the total amount of deployments that were made. For example, this link might read 4 more deployments in Production.
Custom environment deployments
Anchor link to section titled "Custom environment deployments"A deployment in a custom environment is triggered when a Git commit is pushed to a branch that matches the following conditions:
- The branch isn't the default branch of the connected Git repository
- The branch is connected to a custom environment
You can access previous deployments by clicking the View all deployments link under a specific custom environment.
Preview deployments
Anchor link to section titled "Preview deployments"A deployment in the preview environment is triggered when a Git commit is pushed to a branch that isn't assigned to a custom environment, and isn't the default branch of the connected Git repository. The deployments in the preview environment contain the latest build of a Hydrogen storefront from a branch that isn't assigned to a custom environment.
Preview URLs
Anchor link to section titled "Preview URLs"Preview URLs link to a specific version of a Hydrogen storefront in an Oxygen environment, and are private by default.
Oxygen provides the following types of preview URLs:
- Environment URLs: A preview of the latest commit that was pushed to a Hydrogen storefront Git repository in a specific environment.
- Deployment URLs: Previews of past commits that were pushed to a Hydrogen storefront Git repository in a specific environment.
To learn how to publish a preview URL, refer to Toggle the privacy of preview URLs.
Environment variables
Anchor link to section titled "Environment variables"Environment variables are used to store reusable data, which can be used in Hydrogen storefront code. Oxygen stores environment variables with the app code. You can add environment variables to Oxygen environments, or you can import environment variables from other environments.
The following table describes the read-only environment variables that Shopify creates and manages, and their equivalent deprecated variables:
Variable | Description | Deprecated variable |
---|---|---|
PUBLIC_STOREFRONT_API_TOKEN |
The public token for the Storefront API. | SHOPIFY_STOREFRONT_API_PUBLIC_TOKEN |
PRIVATE_STOREFRONT_API_TOKEN |
The secret token for the Storefront API. You can rotate the secret token if it's leaked publicly. | SHOPIFY_STOREFRONT_API_SECRET_TOKEN |
PUBLIC_STOREFRONT_ID |
The storefront ID. | SHOPIFY_STOREFRONT_ID |
PUBLIC_STORE_DOMAIN |
The store domain. | SHOPIFY_STORE_DOMAIN |
Depending on how you connect your Git repository, Oxygen might store both current and deprecated read-only environment variables to maintain compatibility with previous Hydrogen versions.
Troubleshooting
Anchor link to section titled "Troubleshooting"In case of bugs and other errors, you can temporarily roll back Oxygen environments to previous deployments. This lets you continue serving a working deployment to users while you work on a fix.
To debug issues with deployments, you can download worker bundles and review runtime logs.
After storefronts are deployed to Oxygen, worker files can access the worker runtime APIs.
- Learn how to create and connect a storefront to the Hydrogen channel.
- Learn how to create custom environments and use them to preview changes without affecting other environments.
- Learn how to create environment variables and use them to store reusable data for use in the Hydrogen storefront code.