Migrating Hydrogen Stores to React Router 7: What You Need to Know

By nuwudorder | September 23, 2025

Introduction

As of May 2025, Shopify has made React Router 7 (RR7) mandatory for Hydrogen. Legacy projects still on React Router 6 must migrate to stay supported.

This migration isn’t just a version bump. RR7 introduces streaming-first APIs, loader changes, and nested routing enhancements that affect how Hydrogen apps render and fetch data.

This post is your migration guide: what’s new, what breaks, and how to move safely.

Why the Migration Matters

  • ⚡ Performance → RR7 enables native defer() streaming for faster TTFB.
  • 🔍 SEO → metadata handling changes improve crawlability.
  • 🛠️ Support → future Hydrogen releases will assume RR7 as baseline.
  • 🔄 Stability → codemods and guardrails reduce boilerplate errors.

What’s New in React Router 7

1. defer() Streaming

  • Native API for streaming non-critical data.
  • Example: stream CMS content while rendering products instantly.

import { defer } from "react-router"; export async function loader() { const product = await fetchProduct(); const cmsPromise = fetchCMS(); return defer({ product, cms: cmsPromise }); }

2. Loader & Action Changes

  • useLoaderData now fully typed in TypeScript.
  • Error handling unified with ErrorBoundary.
  • Actions integrate better with forms + mutations.

3. Nested Routing Enhancements

  • More flexible layouts with parallel routes.
  • Easier to manage PDPs, submenus, and cart overlays without prop-drilling.

Migration Workflow

Step 1. Install Codemods

  • Shopify provides codemods to update loader/action signatures.
  • Run:

npx shopify-hydrogen-codemod rr7 ./src

Step 2. Update Loaders

  • Replace legacy json() loaders with defer() where streaming applies.
  • Ensure fallbacks for SEO (never stream all critical data).

Step 3. Test Nested Routes

  • Refactor layout routes with new parallel routing.
  • Verify menu → PDP → cart overlays render correctly.

Step 4. Verify SEO Metadata

  • <Seo> component hooks into updated loader outputs.
  • Run Screaming Frog or Google Search Console to confirm crawlability.

Step 5. Run CI/CD Guardrails

  • Playwright flows for PDP/cart/checkout.
  • Lighthouse CI for CWV.
  • Subrequest profiling to ensure no regressions.

Common Pitfalls

  • ❌ Forgetting fallbacks in defer() loaders → Googlebot indexes “Loading…” text.
  • ❌ Breaking nested routes → layouts must be restructured.
  • ❌ Over-streaming → too many deferred calls increase TTFB.
  • ❌ Ignoring codemod warnings → missing type coverage.

Case Study: Agency Upgrade

  • Agency migrated 12 Hydrogen storefronts to RR7.
  • Issues: loaders broke, cart overlays misfired.
  • Fixes: added fallback states, restructured nested layouts, enforced defer() only for non-critical CMS/reviews.
  • Outcome: +15% faster TTFB, SEO stability maintained, migration completed in 3 weeks.

Best Practices

  • ✅ Run codemods early.
  • ✅ Stream selectively — not critical SEO content.
  • ✅ Audit nested routes for layout consistency.
  • ✅ Add SEO checks to CI/CD pipeline.
  • ✅ Train devs on new loader/action patterns.

Conclusion

React Router 7 is the foundation of Hydrogen going forward. The migration unlocks faster streaming, cleaner loaders, and better routing — but only if handled carefully.

Treat RR7 migration as a refactor, not just an upgrade.

Posted in Blog

About nuwudorder