Hydrogen on React Router 7: what actually changed

Key takeaways

• Hydrogen's framework layer moved from Remix v2 to React Router 7. The Storefront API client, caching and Oxygen hosting work as they did.
• Most of the change is imports and build config: the @remix-run/* packages give way to react-router and @react-router/*.
• The official codemod does most of the mechanical work; custom server code, route config and third-party packages need a developer.
• Turn on every Remix future flag before you start — each one enabled first is one fewer surprise later.
• For a typical store it is a focused sprint plus regression testing, not a rebuild.

When the Remix team merged Remix into React Router 7, Shopify followed. Hydrogen — Shopify's headless storefront framework — now builds on React Router 7, and from mid-2025 it became the supported path: Remix-based Hydrogen projects have to migrate to keep receiving framework updates. If your store already runs on Hydrogen, this is what the move really involves.

Why Hydrogen moved to React Router 7

Remix and React Router had been converging for years. Remix's loaders, actions, nested routes and streaming were built on React Router all along, and React Router 7 absorbed the rest as its framework mode. Remix v2 became, in effect, React Router 7 under different package names — so staying on Remix would have meant staying on a branch with no future.

For merchants the headline is reassuring: this was a change of foundations, not of features. Nothing about how a Hydrogen storefront talks to Shopify had to change.

What actually changed

• Package names: Imports from @remix-run/react and @remix-run/server-runtime now come from react-router. Most shared APIs that were re-exported through runtime-specific packages collapsed into that one package.
• Build tooling: The Remix Vite plugin is replaced by React Router's (@react-router/dev), with a react-router.config.ts next to vite.config.ts.
• Route configuration: Routes are declared in app/routes.ts. File-based routing still works through @react-router/fs-routes, so an existing routes folder can stay as it is.
• Data loading: Loaders return plain objects instead of wrapping them in json(), and promises stream without defer() — the single-fetch behaviour Remix introduced behind a future flag is simply how it works now.
• Type safety: React Router generates types for each route's loader data and params, so mismatches that used to fail at runtime now fail in the editor.

What did not change

The parts of Hydrogen that make a store a store carried over untouched:

• Storefront API queries through context.storefront, with the same caching strategies.
• Hydrogen's commerce components and utilities — cart handling, Money, Image, SEO helpers and analytics.
• The Customer Account API integration.
• Deployment to Oxygen, Shopify's hosting for Hydrogen, and the Shopify CLI workflow around it.

How to migrate a live Hydrogen store

We run every migration on a branch deployed to an Oxygen preview environment, and only switch production once the money paths are proven. The sequence:

1. Upgrade within Remix first. Move to the latest Remix-based Hydrogen release and enable every Remix v2 future flag, one at a time, fixing what each one surfaces.
2. Run the codemod. npx codemod remix/2/react-router/upgrade rewrites imports and configuration across the project.
3. Finish what the codemod cannot. Custom server entry files, route configuration and dependencies that still import from @remix-run need a developer.
4. Let the Hydrogen CLI help. npx shopify hydrogen upgrade walks through Hydrogen's version bumps and their breaking changes.
5. Regression-test the revenue paths. Collection and product pages, cart, checkout handoff, customer accounts and analytics events — then compare Core Web Vitals before and after.
6. Ship behind a preview. Share the Oxygen preview URL with the team, then promote the deployment once it holds up.

Snags we see most often

• Third-party packages: Libraries that still import from @remix-run/* break the build until they are updated or replaced.
• Leftover json() and defer(): Old helpers linger in places and behave differently under single fetch; clearing them out is part of the job.
• Custom server code: Anything added to the server entry — redirects, headers, proxies — has to move to the new structure by hand.
• New type errors: Route typegen surfaces mismatches that were always there. Treat them as free bug reports, not noise.

Should you migrate now?

If your store is on a Remix-based Hydrogen release, yes. Framework updates, security fixes and new Hydrogen features ship for React Router 7, and the longer a store drifts from the supported path, the bigger the eventual jump. For most storefronts the migration is a focused sprint plus testing; heavily customised builds can take two.

We run Remix to React Router 7 migrations and headless Hydrogen builds with the same five-stage process as every project. If you would like a second opinion on your storefront first, tell us about it.