Hydrogen example storefront with advanced caching patterns

Hydrogen is Shopify’s stack for headless commerce. Hydrogen is designed to dovetail with Remix, Shopify’s full stack web framework. This template contains a minimal setup of components, queries and tooling to get started with Hydrogen.

Clone and deploy this example

Deploy your own version of this example site, by clicking the button below. This will automatically:

Clone a copy of this example from the examples repo to your own GitHub account
Create a new site in your Netlify account, linked to your new repo
Create an automated deployment pipeline to watch for changes on your repo
Build and deploy your new site

More examples

Explore other examples of using the Netlify platform and primitives (with or without a framework) in this examples repo.

See also our Hydrogen template without caching.

What's included

Remix 2
- Check out Hydrogen docs
- Get familiar with Remix
Hydrogen
Shopify CLI
Configured deployment to Netlify, with Server-Side Rendering (SSR) via Netlify Edge Functions
ESLint
Prettier
GraphQL generator
TypeScript and JavaScript flavors
Minimal setup of components and routes
SSR page response caching by with Stale-While-Revalidate by default, with per-page overridable configuration
SSR resource route response caching (used for CSR) with Stale-While-Revalidate by default, with per-page overridable configuration
Caching configured to vary appropriately on scaffolded pages (i.e. products vary on variant options, search varies on query, etc.)
Cache tag set on product pages with Shopify product ID
Shopify webhook handler which invalidates the product's page when a product is updated

Getting started

Requirements:

Node.js version 18.0.0 or higher
Netlify CLI 17.0.0 or higher

npm install -g netlify-cli@latest

To create a new project, click the "Deploy to Netlify" button above, follow the prompts, and you're ready to start developing.

Local development

npm run dev

Building for production

npm run build

FAQ and Troubleshooting

How do I configure my Hydrogen session / storefront client / customer account client / cart handler?

See app/lib/context.ts and the Hydrogen documentation.

How do I augment the Remix context?

Add your custom context to the object returned by the createAppLoadContext function in app/lib/context.ts and ensure the return type is updated (e.g. HydrogenContext & {foo: string}).

How do I configure a real Shopify store in local dev?

See .env.example and these Shopify instructions.

I get a 500 error on the `/accounts` pages. How do I configure real Shopify customer accounts in local dev?

See these Shopify instructions.

Static assets not loading in local dev

If your .js and .css files are failing to load in local development (with 404 responses), you may be running into an issue that occurs when netlify dev is run after having run a build (via netlify build, netlify serve, npm run build, or remix vite:build). This is a known issue that Netlify is working on.

To fix this, delete the conflicting built functions before running your dev server:

rm -rf .netlify/edge-functions*
npm run dev

`shopify hydrogen preview` fails with `Cannot find module '@shopify/mini-oxygen'`

The shopify hydrogen preview command has a misleading name. It previews your site in a local simulation of the Oxygen hosting platform. It therefore isn't compatible with a site intended to be deployed to Netlify.

Instead, use the Netlify CLI (e.g. netlify serve).