Hydrogen and Oxygen project structure
Hydrogen and Oxygen make up Shopify's recommended stack for headless commerce. The different parts of the system work together to make it faster and easier to build and deploy headless Shopify stores.
- Hydrogen: A set of components, utilities, and design patterns for working with with Shopify APIs.
- Remix: The underlying framework that handles routing, data fetching, reactive UI, and styling.
- Oxygen: Runs Hydrogen apps at the edge and handles rendering, caching, static assets, and event logging.
The following diagram is a simplified visualization of how the different parts of the Hydrogen and Oxygen stack work together:

Hydrogen app structure
Anchor link to section titled "Hydrogen app structure"A Hydrogen project starts with a standard Remix app. The following example shows the directory structure of the most basic Hydrogen app:
Key files to understand
Anchor link to section titled "Key files to understand"This is your app’s main entry point. In Hydrogen, this file does the following important things:
- It creates the API client that allows your app to query Shopify’s Storefront API.
- It creates the handler that allows you to manage Hydrogen’s cart component.
- It provides a cookie-based session management utility.
app/root.jsx
Anchor link to section titled "app/root.jsx"This is Hydrogen’s root route. It renders the HTML that wraps every page in your app, so it’s the recommended place to include global <link>
, <meta>
, or <script>
tags. This file is also where you should define a Remix loader for any global data.
app/entry.client.jsx
Anchor link to section titled "app/entry.client.jsx"This is the entry point for the browser bundle. This file allows you to control client-side hydration after JavaScript loads.
app/entry.server.jsx
Anchor link to section titled "app/entry.server.jsx"This is the entry point for the server-side rendered response that gets sent to the browser. This file allows you to control the HTTP response code, headers, and HTML markup.
remix.config.js
Anchor link to section titled "remix.config.js"The Remix configuration file controls options for local development and your project build step. This file doesn’t run on the production server.
This is a directory for storing static assets like images and other static files. Everything within this directory gets uploaded to Shopify's CDN when you deploy to Oxygen.
Packages and dependencies
Anchor link to section titled "Packages and dependencies"Hydrogen comes bundled with a set of dependencies that work together to make it easier to manage end-to-end app development and deployment. The following table presents some key packages to be aware of:
Package | Description |
---|---|
@shopify/hydrogen |
The main Hydrogen package. It contains Remix-specific components and utilities that you use to build Hydrogen apps. This package extends @shopify/hydrogen-react , which contains framework-agnostic components. Learn more about Hydrogen React. |
@shopify/hydrogen-cli |
The Hydrogen plugin for the Shopify CLI. Refer to the complete list of Hydrogen CLI commands. |
@shopify/mini-oxygen |
The development server for Hydrogen apps. It aims to provide near-parity with the Oxygen hosting runtime that runs in production. |
@shopify/remix-oxygen |
A Remix adapter that enables Hydrogen to be served on Shopify’s Oxygen hosting platform. |
The Hydrogen channel
Anchor link to section titled "The Hydrogen channel"The Hydrogen channel is a sales channel that you install on your Shopify store. It coordinates all the various services and platforms that make up the Hydrogen and Oxygen stack. It also allows you to manage storefronts, environments, deployments, and monitoring through the Shopify admin.
The Hydrogen channel handles the following key tasks:
- Enables a sales channel in which you can publish product inventory.
- Enables access to the Oxygen hosting runtime.
- Watches any connected GitHub repositories for code updates to deploy to Oxygen.
- Allows you to manage deployment environments, including environment variables.
- Provides event logging for individual deployments.
Shopify GitHub app
Anchor link to section titled "Shopify GitHub app"The Shopify GitHub app enables you to connect a GitHub account to your Shopify admin. This connection enables you to make and track changes to Hydrogen storefront code, and enables you to collaborate with other developers to share progress.
How it works
Anchor link to section titled "How it works"The Shopify GitHub integration enables you to connect your Hydrogen storefront code to the Oxygen hosting platform. When you push commits to a connected Git repository, the commits trigger a deployment with a preview URL to the environment, enabling you to quickly preview your changes throughout the development process.
Connection to GitHub
Anchor link to section titled "Connection to GitHub"You can connect only one GitHub account to your Shopify login. After you connect your Shopify login to a GitHub account, your Shopify login can connect repositories and branches that the Shopify GitHub app has access to.
If multiple users need to manage connections to a repository, then each user needs to authorize the Shopify GitHub app for their own account.
To disconnect your GitHub account or organization from the Shopify store, you can uninstall the Shopify GitHub app through GitHub.
Change a GitHub account into a GitHub organization
Anchor link to section titled "Change a GitHub account into a GitHub organization"If you've changed your GitHub user into a GitHub organization while having the Shopify GitHub app installed, then you need to uninstall and reinstall the app so that Shopify can connect to new repositories.
GitHub permissions
Anchor link to section titled "GitHub permissions"The Shopify GitHub app requires the following permissions to access certain data in your GitHub account or organization:
Read-only access | deployments, metadata |
---|---|
Read and Write access | administration, code, pull requests, secrets, workflows |
Limitations
Anchor link to section titled "Limitations"- Branch connections and commits from GitHub to Shopify can be a maximum of 50 MB overall, and 5 MB for each file.
- The number of pushes and pulls that you can make using the Shopify GitHub integration is controlled by standard GitHub app rate limits.
Repository connection management
Anchor link to section titled "Repository connection management"If Shopify loses access to your GitHub repository, then your Hydrogen storefront will disconnect and new deployments to Oxygen will stop. Existing deployments aren't affected. You can reconnect to a GitHub repository from the Integrations page in your Hydrogen storefront's settings.
Shopify can lose a connection to a GitHub repository in the following ways:
- Shopify GitHub app suspended or deleted
- Shopify GitHub app's access to a repository removed
- Repository deleted or archived
- Repository transferred to another account
Oxygen hosting
Anchor link to section titled "Oxygen hosting"Hydrogen is optimized for deployment to Oxygen, Shopify’s serverless edge hosting platform. Oxygen is available at no extra charge on Basic, Shopify, Advanced, and Plus plans. It isn't available for Starter plans or development stores.
Oxygen is a worker-based JavaScript runtime that adapts web browser APIs to the server context. This means you can access standard web platform features such as the Fetch API, Cache API, HTTP Headers, Streams, the Web Crypto API, and more. Some Node.js APIs aren't available. Check Cloudflare's Node.js compatibility documentation for full details, or consult the complete list of Oxygen runtime features.
Oxygen limitations
Anchor link to section titled "Oxygen limitations"- You can use Oxygen for hosting commerce storefronts. The platform is subject to the Shopify Acceptable Use Policy. Misuse or abuse of Oxygen might lead to throttling, suspension, or termination.
- Built worker file limitations:
- Workers must be 10 MB or less.
- Workers are limited to 30 seconds of CPU time per request.
- Worker can consume a maximum of 128 MB of memory. If your worker file exceeds this limit, then requests for your worker might get cancelled.
- Static assets have maximum file sizes, based on the asset type:
- Images: 20 MB
- Videos: 1 GB
- 3D models: 500 MB
- Other files: 20 MB
Content Delivery Network
Anchor link to section titled "Content Delivery Network"Oxygen uses Shopify's content delivery network to compress, convert, and serve your storefront's assets in an optimized way.
By default, when a Hydrogen storefront is built and deployed, any new assets are automatically deployed to Shopify's content delivery network, and any application references are converted to use the cdn.shopify.com
domain.
Oxygen also attempts to serve assets on your storefront's domain for requests to paths like /.well-known/
and other files that need to be served from the same domain. If a request for an asset on the storefront domain can't be served, then Oxygen falls back to serving that storefront request from the Hydrogen app.
Consult the complete list of Oxygen runtime features.
Oxygen GitHub Action
Anchor link to section titled "Oxygen GitHub Action"Shopify connects to GitHub in order to enable continuous deployment of your Hydrogen app to the Oxygen hosting platform. Deployments are controlled by an Oxygen workflow file in your Hydrogen app. This is an example of what an Oxygen workflow file looks like:
This is a standard workflow file for GitHub Actions and you can edit it to meet your needs. However, there are few key points you should be aware of:
Don't change the line below!
refers to the immediate line following, which contains the app's associated storefront ID. This line is required to make deployments to Oxygen.- The "Build and Publish to Oxygen" step uses a Shopify-managed GitHub action called
shopify/oxygenctl-action
. This action is required to make deployments to Oxygen. If you remove this step, then deployments won't be completed. - By default, the workflow installs app dependencies with npm. If you use a different package manager, then you’ll need to edit this file to prevent errors caused by multiple lockfiles, as well as to manage module caching.
Alternate package managers
Anchor link to section titled "Alternate package managers"If you're using a package manager other than npm, such as Yarn or pnpm, note the following:
- Hydrogen and Oxygen use npm by default. Shopify can’t guarantee compatibility with other package managers.
- The Oxygen deployment workflow file uses npm by default, and assumes the presence of a
package-lock.json
file. You can edit the workflow file to use your preferred package manager. In particular, check that the steps to install dependencies, cache modules, and build your app are updated to use the correct commands.