Shopify Hydrogen: six packages pinned to Shopify's API calendar

Opinionated React Router tools sit beside a portable React library

Shopify presents Hydrogen as its stack for headless commerce: a set of tools, utilities and worked examples for commerce applications, not a hosting service. The monorepo splits into two philosophies. `@shopify/hydrogen` is the opinionated one, aimed squarely at applications built with React Router, where the router shapes the recommended structure of the app. `@shopify/hydrogen-react` sits on the other side, a library of Shopify-specific commerce components, hooks and utilities that stays out of routing decisions. Hydrogen is designed to dovetail with React Router, but it also provides a React library portable to other supporting frameworks, and that second package is the escape hatch for teams whose router is already decided. The README leaves one thing open: it does not name a single one of those supporting frameworks, so portability here is a stated intention rather than a compatibility list you can plan against. Anyone evaluating Hydrogen should first decide which of the two packages they actually want, because the answer determines how much of their own architecture survives the upgrade.

Calver pins each Hydrogen build to one Shopify API snapshot

Versioning is where this framework parts company with most React tooling. Hydrogen and hydrogen-react are tied to specific versions of the Shopify Storefront API and the Customer Account API, and both of those follow calver. The mapping is explicit: if your API version is `2025-07`, then Hydrogen and hydrogen-react versions `2025.7.x` are fully compatible with it. Because Shopify updates API versions every three months, breaking changes in Hydrogen can arrive on that same cadence, which ties your upgrade planning to an API calendar you do not control.

The repository does not leave that convention to prose alone. Its root `package.json` carries four scripts dedicated to it, and `test:calver` runs `./.changeset/test-calver-comparison.sh` while `test:calver:dry` runs `node .changeset/enforce-calver-local.js --dry-run`. A mismatch between your API version and your package version is a build failure rather than a runtime surprise, which is the correct trade for a framework that rewrites data access for you.

The install guide says npm while the repository pins [email protected]

A close look at the getting-started steps turns up a mismatch worth settling before you start. The install instructions offer npm or your package manager of choice, such as `yarn` or `pnpm`, and the scaffold command is written with npm. The repository's own root file declares something stricter:

"packageManager": "[email protected]",
"private": true,
"sideEffects": false,

The tree also ships `pnpm-lock.yaml` and `pnpm-workspace.yaml`, so anyone following the README literally ends up with an npm lockfile sitting beside a pinned pnpm workspace. Task orchestration splits the same way. Building all packages runs `turbo build --parallel --filter=./packages/*`, templates build separately through `turbo build --parallel --filter=./templates/*`, and a single app starts with `turbo dev --filter=skeleton`, pointing at the skeleton template that doubles as the project homepage. Continuous integration bundles `turbo run lint test format:check typecheck` into one pass, so a lint failure, a broken test, a formatting drift and a type error all surface together instead of one at a time. The repository is MIT licensed and the last push was on 2026-09-28.

Scaffolding a storefront and reading it on port 3000

Two requirements come before anything else: Node.js version 22 or 24, plus a package manager. npm works, and so do yarn and pnpm, but the repository pins [email protected] for its own workspace, a decision worth making up front rather than after the first lockfile.

Scaffolding is one create command:

npm create @shopify/hydrogen@latest

That writes a new app into the current directory. Two further commands install its dependencies and start the development server:

npm install
npm run dev

The app comes up on port 3000, linked in the getting-started list as `http://localhost:3000`. Beyond that, very little is documented for a first run. There is no list of flags for the create command, no note about which environment variables a fresh app expects, and no troubleshooting section for a scaffold that fails halfway. The numbered list stops at those two commands and then links out to the full documentation, so plan on reading the docs before your first store connection rather than after it.

Two packages sit outside calver and one build is a preview

Calver covers `@shopify/hydrogen` and hydrogen-react by name. The rest of the package table follows its own scheme. The newest published `@shopify/[email protected]` and `@shopify/[email protected]` both appeared on 2026-09-24, plain semantic versions carrying no API year at all. The newest published `@shopify/[email protected]`, dated 2026-09-11, is a three-part number with a preview suffix rather than the two-part `2025.7.x` shape the versioning section describes. Read that as the boundary of the compatibility rule: it binds the two commerce packages and stops short of the CLI, the scaffolder, codegen and the local runtime.

`@shopify/mini-oxygen` deserves the closest look from anyone weighing the stack. Its description calls it a local runtime for Hydrogen apps that simulates the Oxygen production environment, which places it between the dev server on port 3000 and whatever runs in production. Its number sits at 4.2.3 while the CLI sits at 13.0.5, and those two move independently of the hydrogen packages, so pinning one of the six leaves the other five unconstrained on their own.

Codegen, GraphQL config and agent files share one tree

The top level shows how much lives in this repository rather than in your app. `@shopify/hydrogen-codegen` generates types for Storefront API and Customer Account API queries automatically, and the root `.graphqlrc.yml` gives editors something to validate those queries against. Below `packages/` sit `templates/` for generated apps, `cookbook/` for recipes, `e2e/` with a `playwright.config.ts` at the root for browser-level checks, and `rfc/` for design discussion.

Three entries there have nothing to do with storefront code. `.mcp.json`, `CLAUDE.md`, `.claude/` and `.cursor/` are agent configuration and instruction files committed alongside the packages. `secrets.ejson` holds encrypted values, unlocked locally through `ejson decrypt secrets.ejson` and re-encrypted with `ejson encrypt secrets.ejson`. Even the install hook is wired: `prepare` runs `husky && node scripts/patch-cli.mjs`, so a git hook and a CLI patch step both fire before you touch any source. Contributors should expect a repository that ships tooling around the framework, not only the framework itself.

Three costs behind the calendar, the coupling and the thin escape hatch

Three costs sit behind the convenience. First, the schedule: Shopify updates its API versions every three months and breaking changes can follow that cadence, so a storefront built on Hydrogen inherits a migration rhythm it did not choose. Second, the coupling. Both commerce packages are defined against the Storefront API and the Customer Account API, and no package in the table targets a backend that is not Shopify, so decoupling later is not a configuration change.

Third, the escape hatch is narrower than it reads. `@shopify/hydrogen-react` is portable to other supporting frameworks, yet the README names none of them, and calling it unopinionated is not the same as documenting what it runs on. The getting-started list also documents no upgrade path between two Hydrogen versions and no rollback procedure, and the version rules bind two of six packages. Teams on the earlier line already sit outside this repository: Hydrogen legacy v1 was moved to a separate repository with its own tutorial documentation, and this repository's topic list still carries `remix` beside `react` even though the stack is now built on React Router.

Editorial conclusion

Hydrogen earns its place for teams already selling on Shopify who have accepted React Router as the rendering layer and can schedule work around Shopify's three-month API calendar. It does not earn its place for a team hoping to decouple its storefront backend later, because every Hydrogen version is pinned to one Storefront API snapshot. Before adopting, confirm your API version maps to the matching calver series, then read what `enforce-calver-ci.js` rejects in your build, and remember that the rule binds only two of the six packages in the table.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Shopify/hydrogen on GitHub