React Router 7 in Hydrogen: What Changed and How to Upgrade

Introduction

Shopify Hydrogen relies on React Router as its navigation backbone. With the release of React Router 7, developers building headless storefronts face a new reality: route handling, loaders, and actions all come with subtle but important changes.

In this post, we’ll break down what changed in v7, how it impacts Hydrogen projects, and the smoothest upgrade path — including codemods that make migration less painful.

Why React Router Matters in Hydrogen

Hydrogen is essentially React Router + Shopify utilities. That means every route, loader, and action you write is shaped by React Router’s APIs. When the router changes, Hydrogen developers feel it immediately.

Key Changes in React Router 7

1. Route Definitions Are Simpler

• Old (v6):
• <Route path="/products/:id" element={<Product />} />
• New (v7):
• { path: "/products/:id", element: <Product />, loader: productLoader, }

Hydrogen developers will appreciate how this lines up with its file-based routing model.

2. Loader & Action Updates

• Errors thrown in loaders → automatically bubble to error elements.
• Redirects → standardized return type instead of throw hack.
• Hydrogen tie-in → cart + product loaders map more cleanly to the new API.

3. Data Routers as Default

React Router 7 assumes data APIs (loaders, actions) are the norm. For Hydrogen:

• Product pages → use loaders for Storefront API queries.
• Checkout flows → use actions for mutations (add-to-cart, apply discount).
• This aligns perfectly with Shopify’s “data-first” approach.

4. Better Suspense Integration

React Router 7 plays nicer with React 18 concurrent rendering.

• SSR + streaming → less boilerplate for Suspense boundaries.
• Hydrogen developers benefit with smoother streaming SSR → faster TTFB.

Upgrade Path for Hydrogen Developers

Step 1: Run Codemods

React Router provides codemods to migrate route definitions:

npx react-router-codemod v7 <src>

Step 2: Update Loaders/Actions

• Replace legacy throw/redirect hacks with new return types.
• Refactor error handling into <ErrorBoundary>.

Step 3: Test SSR/Streaming

• Use npm run dev in Hydrogen → confirm loaders stream correctly.
• Run Lighthouse → validate TTFB didn’t regress.

Example: Hydrogen Product Route Migration

Before (v6-style Hydrogen):

export async function loader({ params }) { return await storefront.query(PRODUCT_QUERY, { variables: { id: params.id } }); }

After (v7-style):

export async function loader({ params }) { const data = await storefront.query(PRODUCT_QUERY, { variables: { id: params.id } }); if (!data) return redirect("/404"); return data; }

Error boundaries + redirects are now first-class instead of ad-hoc.

Best Practices

• ✅ Use loaders for all Storefront API queries.
• ✅ Use actions for mutations (checkout, cart, account).
• ✅ Add error boundaries per route — don’t rely on global fallback.
• ✅ Run codemods early → catch breaking changes before Shopify updates Hydrogen templates.

Conclusion

React Router 7 isn’t just an upgrade — it’s a better fit for Hydrogen’s philosophy. By leaning into loaders, actions, and data-first routing, Shopify developers get cleaner code, better streaming, and fewer edge-case hacks.

In Shopify’s Hydrogen era, upgrading to React Router 7 is less about fixing breakage and more about unlocking cleaner patterns.