React Router 7 Preparation

Version 2025.4.0 and higher for @shopify/hydrogen and @shopify/hydrogen-react have adopted React Router 7. Along with the Vite migration, these are additional required tasks for when Pack also adopts React Router 7 later this year and Pack stores are able to update to storefront version 2025-04.

Things to Consider

After every task, ensure localhost launches and runs as expected. Address any server or client side errors accordingly. Do not go live without proper QA of the migration.

For every task under Manual Setup , there is a corresponding prompt under A.I. Prompts that may be passed into an LLM for automating each task. These prompts have been tested internally using the IDE Cursor. Going this route will require some baseline knowledge of using Cursor's AI. Adjust chat settings accordingly:

  1. Turn on Agent mode
  2. Turn on Auto-Run Mode to allow agent to write files without asking for permission each time

Note, every prompt is still subject to the following from the chat:

  • Claim it has finished the task, but on review has still missed action items or has not done a 100% search of the codebase for the instances to change. In that case, prompt the chat that it has not actually finished the job and monitor accordingly.
  • Add additional - or edit/remove current - code or logic that was not asked of it. In that case, prompt it to undo what it just did, but only if it was the last thing it did. If this mistake was noticed later, this may require manual intervention by comparing to what was done with the manual steps.
  • Ask for approval in chunks.

If you are unsure if the A.I. has finished the job completely, reference the manual setup steps and cross reference with what was done from the chat.

Manual Setup

Vite Migration

Priority: Required

Purpose: Vite is required for React Router 7, so all Required steps from Vite Migration documentation must be done first

Route Configuration

Priority: Required

Purpose: Required for React Router 7 migration

  1. Add v3_routeConfig: true to the future object in remix({...}) in vite.config.ts
  2. Add routes.ts to the /app folder
import {flatRoutes} from '@remix-run/fs-routes';
import {hydrogenRoutes} from '@shopify/hydrogen';
import type {RouteConfig} from '@remix-run/route-config';

export default hydrogenRoutes([...(await flatRoutes())]) satisfies RouteConfig;

Relevant Blueprint release commits:

Only use Blueprint commits as references, as some may be incomplete, outdated, or include unrelated changes to the task. Refer to the steps outlined above.

Single Fetch Updates

Priority: Required

Purpose: Required for React Router 7 migration

Note: If you have already replaced all your json() utilities based on a previous Blueprint release, please ensure step 2 has been accounted for and update accordingly

  1. Go through all files under the app/routes folder, and locate all the instances where the utility json() (imported from @shopify/remix-oxygen) is being returned. Quickest way is to identify for all instances is to search for return json( exactly

  2. If the file is a resource route, follow the steps below. A resource route is a route that only has a loader and/or action and does not render a component. In the case of Blueprint, it's all routes prefixed ($locale).api., as well as ($locale).account.login.multipass.tsx

    1. Replace all instances of json() with Response.json(), e.g. change return json(data, options) to Response.json(data, options)

  3. For all other files, e.g. files that return a component:

    1. If json is being returned with only one argument, e.g. return json({page, url}) or return json(data), then remove the json() utility and just return the object, e.g. return {page, url} or return data
    2. If json is being returned with two arguments, where the second argument is options, then import data from @shopify/remix-oxygen and give it an alias like dataWithOptions. Then replace json with dataWithOptions, e.g. return dataWithOptions({page}, {status})

Relevant Blueprint release commits:

Only use Blueprint commits as references, as some may be incomplete, outdated, or include unrelated changes to the task. Refer to the steps outlined above.

A.I. Prompts

Vite Migration

See Vite Migration docs

Route Configuration

Prompt:

1. Add `v3_routeConfig: true` to the `future` object in `remix({...})` in `vite.config.ts`
2. Add `routes.ts` to the `/app` folder, and add following code:
/* Code starts below. Do not include this line */
import {flatRoutes} from '@remix-run/fs-routes';
import {hydrogenRoutes} from '@shopify/hydrogen';
import type {RouteConfig} from '@remix-run/route-config';

export default hydrogenRoutes([...(await flatRoutes())]) satisfies RouteConfig;
/* Code ends above. Do not include this line */

Single Fetch Updates

Prompt:

1. Go through all files under the `app/routes` folder, and locate all the instances where the utility `json()` (imported from `@shopify/remix-oxygen`) is being returned. Quickest way is to identify for all instances is to search for `return json(` exactly
2. If the route is prefixed `($locale).api.`, or is `($locale).account.login.multipass.tsx`_, do the following:

   1. Replace all instances of `json()` with `Response.json()`, e.g. change `return json(data, options)` to `return Response.json(data, options)`

3. For all other routes:
   1. If `json` is being returned with only one argument, e.g. `return json({page, url})` or `return json(data)`, then remove the `json()` utility and just return the object, e.g. `return {page, url}` or `return data`
   2. If `json` is being returned with two arguments, where the second argument is options, then import `data` from `@shopify/remix-oxygen` and give it an alias `dataWithOptions`. Then replace `json` with `dataWithOptions`, e.g. `return dataWithOptions({page}, {status})`
4. Remove all imports of `json` from `@shopify/remix-oxygen` from each of those files

Keep this in mind during the job:
1. Execute with all batches at once without asking for permission to continue, or to stray from the prompt
2. After completion, do one more check of all the files under the app/routes to make sure you did not miss anything

Was this page helpful?