Hydrogen framework overview
Hydrogen includes a framework that offers a set of best practices and scaffolding for building a website. This guide provides an overview of Hydrogen's architecture and framework.
What's the Hydrogen framework?
Anchor link to section titled "What's the Hydrogen framework?"Hydrogen is the approach you use to build a custom storefront. The Hydrogen framework includes a Vite plugin that offers server-side rendering (SSR), hydration middleware, and client component code transformations.
Hydrogen project structure
Anchor link to section titled "Hydrogen project structure"Hydrogen offers different templates that provide paths to building Shopify custom storefronts:
- Hello World: A minimal template for developers who want to build their Hydrogen storefront from the very beginning
- Demo Store: A full-featured template that demonstrates an opinionated, production-ready Hydrogen storefront with the full purchase journey out-of-the-box
For more information, refer to Hydrogen templates.
Request workflow for Hydrogen apps
Anchor link to section titled "Request workflow for Hydrogen apps"The following diagram shows the request workflow for Hydrogen apps, based on the platform where Hydrogen is being hosted:
Node.js runtime
Anchor link to section titled "Node.js runtime"The Hydrogen app is hosted on a Node.js platform like Heroku, Vercel, or Netlify. If you've generated a Node.js server, then you can run it inside a Docker container like GCP, AWS, Azure, or Fly.io.
By default, Hydrogen includes a @shopify/hydrogen/platforms/node package, which is a Connect-based Node.js server. Alternatively, you can use your own server.
Worker (v8) runtime
Anchor link to section titled "Worker (v8) runtime"The Hydrogen app is hosted on a worker platform like Oxygen or Cloudflare.
By default, Hydrogen includes a @shopify/hydrogen/platforms/worker package for server-side rendering. The Cache API and KV API are powered by Oxygen, Cloudflare, or another runtime adapter.
Configuring default entry points
Anchor link to section titled "Configuring default entry points"Hydrogen includes the following default entry points for your app:
- Client entry point:
@shopify/hydrogen/entry-client, which is included inindex.htmland used for hydration purposes - Server entry point:
App.server.jsx
Change the client entry point
Anchor link to section titled "Change the client entry point"If you need to change the client entry point, then create a new file such as src/entry-client.jsx with the following code and update the path in index.html:
Strict mode
Anchor link to section titled "Strict mode"Strict mode is enabled by default for all Hydrogen apps in development. It includes strict effects, which mounts and unmounts components multiple times to catch potential issues with user or third-party code.
If strict effects cause problems for your app, then you can turn off strict mode. Create a src/entry-client.jsx file in your project and set strictMode to false:
Change the server entry point
Anchor link to section titled "Change the server entry point"If you need to change the server entry point, then make the following updates in the package.json file:
- Development: Pass a
HYDROGEN_SERVER_ENTRYenvironment variable to the development command. - Production: Use a
--ssrflag when building your app.
- Get familiar with the different templates that help you get started with Hydrogen.
- Learn about React Server Components, an opinionated data-fetching and rendering workflow for React apps.
- Learn how to deploy your Hydrogen app to Oxygen and other runtimes.