Hydrogen and Oxygen project structure

A Hydrogen project starts with a standard Remix app. The following example shows the directory structure of the most basic Hydrogen app:

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.

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.

This is the entry point for the browser bundle. This file allows you to control client-side hydration after JavaScript loads.

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.

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.

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:

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.

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.

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.

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.

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.

The Shopify GitHub app requires the following permissions to access certain data in your GitHub account or organization:

• 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.

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

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.

• 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

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.

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.

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.