shopify / hydrogen

Hydrogen lets you build faster headless storefronts in less time, on Shopify.

📚 Docs | 🗣 Discord | 💬 Discussions | 📝 Changelog

Hydrogen is Shopify’s stack for headless commerce. It provides a set of tools, utilities, and best-in-class examples for building dynamic and performant commerce applications. Hydrogen is designed to dovetail with Remix, Shopify’s full stack web framework, but it also provides a React library portable to other supporting frameworks.

Hydrogen Legacy v1

Hydrogen legacy v1 has been moved to a separate repo and the docs can be found here.

Getting started with Hydrogen

Requirements:

• Node.js version 16.14.0 or higher
• npm (or your package manager of choice, such as yarn or pnpm)

1. Install the latest version of Hydrogen:

   npm create @shopify/hydrogen@latest

2. Run the local development server:

   npm install
   npm run dev

3. Open your new Hydrogen app running at http://localhost:3000.

See the complete Hydrogen docs.

Packages in this repo

Hydrogen is organized as a monorepo, which includes multiple packages that can be used together.

Package	Latest version	Description	Readme
@shopify/hydrogen		Opinionated tools, utilities, and best-in-class examples for building a commerce application with Remix.	Readme
@shopify/hydrogen-react		Unopionated and performant library of Shopify-specific commerce components, hooks, and utilities.	Readme
@shopify/cli-hydrogen		Hydrogen extension for Shopify CLI.	Readme
@shopify/create-hydrogen		Generate a new Hydrogen project from the command line.	Readme
@shopify/hydrogen-codegen		Generate types for Storefront API queries automatically.	Readme
@shopify/remix-oxygen		Remix adapter enabling Hydrogen to run on the Oxygen runtime.	Readme
@shopify/mini-oxygen		A local runtime for Hydrogen apps that simulates the Oxygen production environment.	Readme

Versioning

Hydrogen and hydrogen-react are tied to specific versions of the Shopify Storefront API, which follows calver.

For example, if you're using Storefront API version 2023-01, then Hydrogen and hydrogen-react versions 2022.1.x are fully compatible.

If the Storefront API version update includes breaking changes, then Hydrogen and hydrogen-react may also include breaking changes. Because the API version is updated every three months, breaking changes could occur every three months.

Learn more about API release schedules at Shopify.

Contributing to Hydrogen

Read our contributing guide

Other handy links

Learn more about Hydrogen.

hydrogen's Issues

[Track] Accounts

#1 (comment)

Authentication

#23 (comment)

Create published NPM package

Create official @hydrogen/remix package which will export:

• Query/Mutation abstraction #28
• Sub-request caching directives #67
• Mini-Oxygen #69
• Shopify Analytics #43

#70 (comment)

Testing

#14 (comment)

Pages (/pages/*)

• /pages/$handle

[Track] Cart

#7 (comment)

Tailwind Setup

Mobile & Desktop navs as dynamic component???

Allbirds didn't just want CSS to hide their navigations … can a dynamic component work? Is there a reason we shouldn't do that? If so — let's explain the perf or accessibility reasons.

Search (/search?q=*)

#11 (comment)

Shopify Analytics

Subject expert: @wizardlyhel

#43 (comment)

Demo Store: Example of small product form on Product Card

Homepage (/)

Add `<track>` element to the Video component for accessiblity

See https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/112261cbc84f5b7d74de9b427b529a10b41faece/docs/rules/media-has-caption.md

Styling

What CSS / Styling strategies can we support? To what quality level? What tradeoffs might come as a result of supporting strategies that Remix doesn't support today?

Must have:

#30 (comment)

Should have:

#30 (comment)

Magic Routes: Shopify Admin (/admin)

https://gist.github.com/benjaminsehl/1c169edcce5b8ef6144156968a2edf16

Magic route at /admin that redirects you to your foobar.myshopify.com/admin URL. Currently exists in Demo Store.

Policies (/policies/*)

• /policies
• /policies/$handle

[Track] Queries/Mutations/Caching

Description

Abstractions to help developers query the Storefront API and caching helpers for other data sources. (PR: #131)

To consider

• RFC
• Demo Store
• Docs
• Types
• Dev Tools
• Configuration
• Extensibility

#28 (comment)

Checkout Button with Preloading

• Automatically add link prefetching to checkout buttons: https://vault.shopify.io/gsd/projects/30199
• Change button element to be a link
• Ask Jason Miller about preloading patterns that work in Safari

Robots (robots.txt)

Demo Store: https://github.com/Shopify/h2-demo-store/blob/main/app/routes/%5Brobots.txt%5D.tsx

Definition of Done: At very least complete inside Demo Store. Consider if we can make the DX of this simpler, like adding a h2 scaffold robots.txt command to the CLI.

#10 (comment)

Implement sub-request caching

Subject expert: @wizardlyhel

See: #58

Need to implement the directives like CacheShort() that we have in Hydrogen into the official NPM package.

#67 (comment)

[BUG] Duplicated HTML `id` due to Hydrogen `<Image />`

Describe the bug

In our designs on Product Details Page, we have a series of image thumbnails with one image that's "selected" and displayed large. We are using the Hydrogen <Image /> component which has the default behavior of setting the HTML id to the underlying id of the image. The result is that we have two <img>s on the page with the same id.

To Reproduce

1. Render a Hydrogen page with two <Image /> components, each that renders the same image
2. Inspect the rendered DOM
3. Notice that there are two <img>s that share the same id

Expected behaviour

I would not expect the Hydrogen <Image /> to set an id. If it did, I'd expect the underlying behavior to guarantee uniqueness via useId or the like.

Screenshots

Additional context
Add any other context about the problem here. eg.

Hydrogen 1.2.0

Script component

Whether or not we leverage it, the impact Partytown can provide (or Zaraz or whatever) for improving the performance impact of third party pixels is a huge point for performance of 2.0

Layout

[Auth] Login with Shop button

Hydrogen-ui should include a <LoginWithShop> component, similar to Hydrogen's implementation of <ShopPayButton>

Connecting Multiple Domains

For example:

• allbirds.ca
• allbirds.com
• allbirds.co.uk
• allbirds.jp
• allbirds.eu

#26 (comment)

[Track] CLI

Original Brief

#29 (comment)

Migrating away from Vite

See https://docs.google.com/document/d/1Plb2cP4CqQBtfZyiTg9_MdPICRvfLkEEz_LjNcPRPAc/edit#heading=h.fbvayv53b7dy

We will likely drop Vite support for Hydrogen v2 and use Remix's native compiler.

#68 (comment)

Error Page

Allow empty alt text on the Image component

Describe the bug
The Image component currently throws warnings when there is no alt text. Sometimes, for presentational images, there should not be alt text. Should an explicit empty string passed as a prop avoid the warning? cc @WillsonSmith

Product Routes (/products/*)

• /products
• /products/$handle
• Update cart

#8 (comment)

Country Selector

[RTE Phase 1] Rich text editor updates in Metafield

Epic: #374898

Renders react components in hydrogen when passed to the Metafield component. This will require recursively traversing the AST, and performantly rendering React components according to the AST.

How does the serializer support current and new plugins?

From the first take, we would have to support updating the serializer for every new plugin.

Link to demo: https://screenshot.click/01-13-f2vi9-ho4dn.mp4

Cart Drawer

Abstraction for AdminRedirects

See snippet… https://gist.github.com/benjaminsehl/1c169edcce5b8ef6144156968a2edf16

Local development in Remix + Oxygen

Remix uses a production runtime for its development environment. This means mini-oxygen will become the primary development tool for Hydrogen users.

#69 (comment)

[Track] i18n

#21 (comment)

Ability to purchase with Apple|Google|PayPal

Description

We need to add the ability to purchase product(s) with Apple Pay.
In Shopify storefronts with Liquid, there are two use cases for the Apple Pay button:

• On the product page
  • When clicked, it opens the Apple Pay flow for purchasing just the product from the product page
• On the cart page
  • When clicked, it open the Apple Pay flow for purchasing the entire cart

Requirements

• The button should only be visible when the merchant has Apple Pay enabled and the buyer is using a supported device for Apple Pay
• When clicked, the Apple Pay checkout flow should be initiated
  • On the product page: for purchasing just that product
  • On the cart page: for purchasing the entire cart
• The button should be rendered by the DynamicCheckoutButton component when appropriate

Notes

• The DynamicCheckoutButton component has a really rough first pass on displaying the ApplePay button (see code here. We'll likely want to extract this code into its own component ApplePayButton and iterate on it from there.

Guide: Connecting Multiple Admins

Similar to Connecting Multiple Domains — but in the context of multiple Shopify stores to a single framework, and a single repo.

Journal (/journal/*)

• /journal
• /journal/$handle

[BUG] Cart doesn't use default Hydrogen localisation

Describe the bug
The CartProvider localisation defaults to US instead of using the project default from Hydrogen config. Only when on the default site, i.e. not /nz, etc.

To Reproduce

1. Start demo store
2. Change defaultCountryCode in Hydrogen config to anything but US
3. See that this isn't reflected in the cart prices

Expected behaviour
Cart country (currency) should be same as that defined in hydrogen.config.ts.

• Hydrogen version (1.3.1)
• Node version (16.15.1)

Sitemap (sitemap.xml)

Brief (Google Doc)

#12 (comment)

[BUG] Product card badge not displaying

Describe the bug


In the current demo store the product badges are not being displayed on the product cards globally. The badge does display of a split second until the product image is loaded.

To Reproduce


1. Open the demo store
2. See a sale product card
3. See the badge display (adjust throttle if needed)

Expected behavior

Badge should display over the product image

Hello World Starter

Product Swimlane

Pagination

See #59

#22 (comment)

SEO

Ask @wizardlyhel for information on SEO requirements and ideal SEO performance behaviour

BOPIS

https://shopify.dev/api/storefront/2022-07/queries/locations

#39 (comment)

Collections Routes (/collections/*)

• /collections
• /collections/$handle
• /collections/all

Sitemap & Product Feed Constraints

Google Doc

404 Page

Should this at all be a magic route? Should there be additional helpers for 404s?

#19 (comment)