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 structureAnchor 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 appsAnchor 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 runtimeAnchor link to section titled "Node.js runtime"
Worker (v8) runtimeAnchor link to section titled "Worker (v8) runtime"
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 pointsAnchor 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 in
index.htmland used for hydration purposes
- Server entry point:
Change the client entry pointAnchor 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
Strict modeAnchor 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
Change the server entry pointAnchor 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
- Development: Pass a
HYDROGEN_SERVER_ENTRYenvironment variable to the development command.
- Production: Use a
--ssrflag when building your app.