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?

Hydrogen is the approach you use to build a custom storefront. It includes a Vite plugin that offers server-side rendering (SSR) and hydration middleware, as well as server and client component code transformations. The SSR and hydration middleware is similar to existing Vite SSR implementations.

Hydrogen comes with React Router, a tool that allows you to handle routes in your app using dynamic routing.

A diagram that illustrates Vite's offering of server-side rendering (SSR) and hydration middleware, and server and client component code transformations

Hydrogen project structure

When you create a Hydrogen app, a file structure for the project is generated. Most of the files that you'll work with in the Hydrogen project are located in the /src directory. The /src directory contains the following:

  • A set of boilerplate components (components) and pages (pages)
  • The main app component, which includes boilerplate code for the app and routing (App.server.jsx)

  • The Hydrogen app's two entry points, which are based on environment:

    • Server: entry-server.jsx
    • Client: entry-client.jsx

  • A shortcut icon (favicon.svg) that you can change to your own favicon

  • Basic styles provided by Tailwind CSS (index.css)

Request workflow for Hydrogen apps

The following diagram shows the request workflow for Hydrogen apps, based on the platform where Hydrogen is being hosted:

A diagram that illustrates the request workflow for Hydrogen apps, based on the platform where Hydrogen is being hosted

Node.js runtime

The Hydrogen app is hosted on a Node.js platform (for example, Heroku, Vercel, or Netlify). Optionally, a Docker container can be used (for example, GCP, AWS, Azure, or Fly.io). The app uses server.js and a Vite development server for server-side rendering, and Node.js middleware.

Worker (v8) runtime

The Hydrogen app is hosted on a worker platform (for example, Oxygen or Cloudflare). The app uses worker.js for server-side rendering. The Cache API and KV API are powered by Oxygen, Cloudflare, or another runtime adapter.

Next steps

On this page