React Router 7

[balazsbajorics]

If you want to try upgrading your Hydrogen Project to React Router 7:

1. Make sure you are on Hydrogen 2025.1.4 with all Remix Future Flags turned on! Make sure your storefront runs fine and commit all changes before proceeding.
   Follow this guide if you haven’t turned on your future flags yet: Hydrogen future flag migration for React Router 7

2. Run npx codemod remix/2/react-router/upgrade – don't worry, after the codemod your project will not be ready yet, we have a few more steps to do:

3. Add react-router.config.ts file with these contents:

import type {Config} from '@react-router/dev/config';

export default {
  appDirectory: 'app',
  buildDirectory: 'dist',
  ssr: true,
} satisfies Config;

4. In vite.config.ts delete all parameters of the reactRouter() plugin. These are just leftovers that the codemod did not clean up.

// if you have declared this type augmentation, delete it
- declare module '@remix-run/server-runtime' {
-   interface Future {
-     v3_singleFetch: true;
-   }
- }

...
export default defineConfig({
  plugins: [
    tailwindcss(),
    hydrogen(),
    oxygen(),
-    reactRouter({
-      presets: [hydrogen.v3preset()],
-      future: {
-        v3_fetcherPersist: true,
-        v3_relativeSplatPath: true,
-        v3_throwAbortReason: true,
-        v3_lazyRouteDiscovery: true,
-        v3_routeConfig: true,
-        v3_singleFetch: true,
-      },
-    }),
+   reactRouter(),
    tsconfigPaths(),
  ],
...

5. Update the hydrogen dependencies to the 0.0.0-snapshot-20250520122031 version

rm -r node_modules
rm package-lock.json

npm install https://registry.npmjs.org/@shopify/cli-hydrogen/-/cli-hydrogen-0.0.0-snapshot-20250520122031.tgz https://registry.npmjs.org/@shopify/hydrogen/-/hydrogen-0.0.0-snapshot-20250520122031.tgz https://registry.npmjs.org/@shopify/remix-oxygen/-/remix-oxygen-0.0.0-snapshot-20250520122031.tgz

6. Change env.d.ts: the declare module should be aimed at react-router and you have to add LoaderFunctionArgs and ActionFunctionArgs (reference file here)

...
- declare module '@shopify/remix-oxygen' {
+ declare module 'react-router' {
...
+  // TODO: remove this once we've migrated to `Route.LoaderArgs` for our loaders
+  interface LoaderFunctionArgs {
+    context: AppLoadContext;
+  }
+
+  // TODO: remove this once we've migrated to `Route.ActionArgs` for our actions
+  interface ActionFunctionArgs {
+    context: AppLoadContext;
+  }
...
}

8. Change tsconfig.json: add ".react-router/types/**/*" to include, and add "rootDirs": [".", "./.react-router/types"] reference file HERE

{
  "include": [
    "./**/*.d.ts",
    "./**/*.ts",
    "./**/*.tsx",
+    ".react-router/types/**/*"
  ],
  "compilerOptions": {
+    "rootDirs": [".", "./.react-router/types"],
    "lib": [
...

10. Add .react-router to the .gitignore file

11. Now try running npm run codegen and npm run typecheck and npm run dev!

[shopify]

Oxygen deployed a preview of your spike-7 branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
classic-remix	✅ Successful (Logs)	Preview deployment	Inspect deployment	April 16, 2025 9:14 PM
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	May 20, 2025 3:20 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	May 20, 2025 3:20 PM
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	May 20, 2025 3:20 PM
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	May 20, 2025 3:20 PM

Learn more about Hydrogen's GitHub integration.

[balazsbajorics]

/snapit

[github-actions]

🫰✨ Thanks @balazsbajorics! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/cli-hydrogen": "0.0.0-snapshot-20250519200352",
"@shopify/hydrogen": "0.0.0-snapshot-20250519200352",
"@shopify/remix-oxygen": "0.0.0-snapshot-20250519200352"

Create a new project with all the released packages running npm create @shopify/hydrogen@<snapshot_version>
To try a new CLI plugin version, add @shopify/cli-hydrogen as a dependency to your project using the snapshot version.

[balazsbajorics]

/snapit

[github-actions]

🫰✨ Thanks @balazsbajorics! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/cli-hydrogen": "0.0.0-snapshot-20250520122031",
"@shopify/hydrogen": "0.0.0-snapshot-20250520122031",
"@shopify/remix-oxygen": "0.0.0-snapshot-20250520122031"

Create a new project with all the released packages running npm create @shopify/hydrogen@<snapshot_version>
To try a new CLI plugin version, add @shopify/cli-hydrogen as a dependency to your project using the snapshot version.

[balazsbajorics]

note to self: have a cursor rule telling the AI that this is now a react-router project, and not a @remix-run/react project.

[brookslybrand]

🎉

[michael-land]

"Follow this document" Why isn’t the migration document publicly accessible if we’re supposed to follow it?

@balazsbajorics

[rbshop]

@michael-land apologies for that, we have since turned that document into a blog post that has been published. I've updated the link to point to https://hydrogen.shopify.dev/update/how-to-adopt-all-future-flags