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.

## Architecture

Three key parts of the Hydrogen stack work together to enable a unified developer experience:

Technology | What it does
---|---
**[Hydrogen](#hydrogen)** <br>(App) | A set of components, utilities, and design patterns that make it easier to work with Shopify APIs. Hydrogen projects are Remix apps that are preconfigured with Shopify-specific features and functionality. Hydrogen handles API client credentials, provides off-the-shelf components that are pre-wired for Shopify API data, and includes CLI tooling for local development, testing, and deployment.
**[Remix](#remix)** <br>(Framework) | The open-source React framework that Hydrogen is built on top of. Remix handles routing, data fetching, server-side rendering, UI reactivity, and styling.
**[Oxygen](#oxygen)** <br>(Hosting) | Shopify’s global serverless hosting platform, built for deploying Hydrogen storefronts at the edge. Oxygen handles deployment environments, environment variable management, caching, and integration with Shopify’s CDN.

Developing each layer of this tech stack together means provides an end-to-end developer experience that reduces boilerplate code, improves productivity, and promotes optimal performance, accessibility, and SEO practices.

## Hydrogen

### Project structure

Hydrogen projects are structured like typical [Remix](#remix) apps and you can configure them to your preferences. The following is the default [Quickstart](/docs/storefronts/headless/hydrogen/getting-started) project structure:

<p>
<div class="react-code-block" data-preset="terminal">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="Hydrogen project structure"></script>
<script data-option="nocopy" data-value="true"></script>

<script type="text/plain" data-language="sh">
📂 hydrogen-quickstart/
├── 📁 app/
│   ├── 📁 assets/
│   ├── 📁 components/
│   ├── 📁 graphql/
│   ├── 📁 lib/
│   ├── 📁 routes/
│   ├── 📁 styles/
│   ├── entry.client.jsx
│   ├── entry.server.jsx
│   └── root.jsx
├── 📁 public/
├── CHANGELOG.md
├── README.md
├── customer-accountapi.generated.d.ts
├── env.d.ts
├── jsconfig.json
├── package.json
├── postcss.config.js
├── server.js
├── storefrontapi.generated.d.ts
└── vite.config.js
</script>

</div>
</p>


### Packages and dependencies

Hydrogen bundles a set of dependencies that work together to enable end-to-end development and deployment:

Package | Description
---|---
<code style="white-space:nowrap">@shopify/hydrogen</code> | Main Hydrogen package. Contains Remix-specific components and utilities for interacting with Shopify APIs. Extends the framework-agnostic [`@shopify/hydrogen-react`](/docs/api/hydrogen-react) package.
<code style="white-space:nowrap">@shopify/hydrogen-cli</code> | CLI tool for working with Hydrogen projects.
<code style="white-space:nowrap">@shopify/mini-oxygen</code> | Local development server based on Oxygen.
<code style="white-space:nowrap">@shopify/remix-oxygen</code> | [Remix adapter](https://remix.run/docs/en/main/pages/technical-explanation#http-handler-and-adapters) that enables Hydrogen to be served on [Oxygen](#oxygen).

### Hydrogen channel

The [Hydrogen sales channel app](https://apps.shopify.com/hydrogen) needs to be installed on your Shopify store to enable the following features:

- A Hydrogen sales channel where you can publish product inventory.
- [Oxygen](#oxygen) hosting, to deploy your Hydrogen projects.
- Managing [storefronts](/docs/storefronts/headless/hydrogen/storefronts) and deployment [environments](/docs/storefronts/headless/hydrogen/environments), including environment variable management.
- Access to deployment logs.

## Remix

Remix is the open-source React-based framework that Hydrogen is built on top of. Hydrogen projects are Remix apps with a set of preconfigured options, bundled with a collection of Shopify-optimized components and utilities. Hydrogen includes a custom Remix adapter that compiles your project for hosting on [Oxygen](#oxygen).

> Remix:
> Consider completing Remix's 30-minute [getting started tutorial](https://remix.run/docs/en/main/start/tutorial) for a solid foundation on the architecture and conventions of Remix apps.

### Key Remix concepts

Concept | Details
---|---
[Nested routes](https://remix.run/docs/en/main/discussion/routes) | Remix maps the nesting logic of app URLs to the nesting logic of components and data-loading. This allows all page data to load in parallel, reducing overall load times.
[Loaders](https://remix.run/docs/en/main/discussion/data-flow#route-loader) | Remix loaders are functions that load data so that it can be rendered server-side, which reduces the amount of JavaScript that's sent to the client. In Hydrogen, loaders fetch data from Shopify APIs and third-party sources.
[Actions](https://remix.run/docs/en/main/discussion/data-flow#route-action) | Remix actions are functions that accept web-standard form data from clients in order to update state, mutate data, or trigger side effects.
[SSR](https://remix.run/docs/en/main/discussion/server-vs-client) | Remix apps default to server-side rendering (SSR), where their React components are rendered as HTML before being sent to the browser.
[Progressive enhancement](https://remix.run/docs/en/main/discussion/progressive-enhancement) | Because Remix actions use web standard technology like HTML forms, they typically work without JavaScript, but can be enhanced with client-side JavaScript when it's available. This, along with an SSR-first approach, means Remix apps typically deliver smaller bundle sizes that load faster.

## Oxygen

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/custom-storefronts/oxygen/oxygen-diagram-eb58f221e35bcf19f4e8d1c447f18e1ea943f6575f13b592a29b44faf09d7829.png" class="lazyload themed-image" data-alt-src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/custom-storefronts/oxygen/oxygen-diagram-dark-da3ad365f01c65b1efbe6d0323be64e04c2ad26abd7c7ce2b959b1e0cd79c253.png" alt="Diagram of how Oxygen interacts with your local Hydrogen project, the Shopify admin, GitHub, and the customer" width="1228" height="616"></figure>

Oxygen is Shopify’s global deployment platform that's built for hosting Hydrogen storefronts at the edge. It provides multiple deployment environments, so you can preview every change before shipping it to production. Oxygen supports continuous deployment using [GitHub](/docs/storefronts/headless/hydrogen/deployments/github), or you can configure your own [custom CI/CD](/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd) system.

Enable access to Oxygen by installing the [Hydrogen channel](#hydrogen-channel).

### Supported plans

Oxygen is available at no extra charge on paid Shopify plans:

- Pause and build
- Basic
- Shopify
- Advanced
- Plus

Oxygen isn't available on Starter plans or development stores.

### Technical specs

Oxygen is a worker-based JavaScript runtime, based on Cloudflare’s open-source [`workerd`](https://github.com/cloudflare/workerd) library. It supports web standard APIs such as Fetch, Cache, Streams, Web Crypto, and more. Some Node.js APIs aren't available. Check the [Oxygen runtime](/docs/storefronts/headless/hydrogen/deployments/oxygen-runtime) details for a complete list.

If you prefer, you can [self-host Hydrogen](/docs/storefronts/headless/hydrogen/deployments/self-hosting).

### Limitations

You can use Oxygen for hosting commerce storefronts. It's subject to the Shopify [Acceptable Use Policy](https://www.shopify.com/legal/aup). Misuse or abuse of Oxygen might lead to throttling, suspension, or termination.

- **Workers:**
  - Must be 10 MB or less
  - The startup time (the duration it takes for the worker to begin processing requests) must be 400 milliseconds or less.
  - Must be named `index.js`. The optional source map file must be named `index.js.map`.
  - Are limited to 30 seconds of CPU time per request
  - Can consume 128 MB max of memory. Exceeding this limit could mean dropped requests.
  - Are limited to 110 [custom environment variables](/docs/storefronts/headless/hydrogen/environments#environment-variables)
- **Static assets, maximum file sizes:**
  - Images: 20 MB
  - Video: 1 GB
  - 3D models: 500 MB
  - Other files: 20 MB

> Caution:
> Ensure your requests go directly to Oxygen. Because proxies can conflict with Oxygen's bot mitigation systems and cause SEO issues, Oxygen doesn't support proxies in front of your Oxygen deployments. 

## Next steps

<div class="resource-card-grid">
  <div>
  <a class="resource-card" href="/docs/storefronts/headless/hydrogen/data-fetching" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/graphql"
     data-alt-src="/assets/resource-cards/graphql-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Fetch product data from Shopify
    </h3>
    <p class="resource-card__description">Learn how to query Shopify’s Storefront API for product data and render it in Hydrogen.</p>
  </a>
</div>
</div>