React Router 7 Preparation
Version 2025.5.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-05
.
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:
- Turn on
Agent
mode - 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:
- Ask for approval in chunks
- 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
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
- Add
v3_routeConfig: true
to thefuture
object inremix({...})
invite.config.ts
- 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:
- commit from release v1.13.1
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
-
Go through all files under the
app/routes
folder, and locate all the instances where the utilityjson()
(imported from@shopify/remix-oxygen
) is being returned. Quickest way is to identify for all instances is to search forreturn json(
exactly -
If the file is a resource route, follow the steps below. A resource route is a route that only has a
loader
and/oraction
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
- Replace all instances of
json()
withResponse.json()
, e.g. changereturn json(data, options)
toResponse.json(data, options)
- Replace all instances of
-
For all other files, e.g. files that return a component:
- If
json
is being returned with only one argument, e.g.return json({page, url})
orreturn json(data)
, then remove thejson()
utility and just return the object, e.g.return {page, url}
orreturn data
- If
json
is being returned with two arguments, where the second argument is options, then importdata
from@shopify/remix-oxygen
and give it an alias likedataWithOptions
. Then replacejson
withdataWithOptions
, e.g.return dataWithOptions({page}, {status})
- If
Relevant Blueprint release commits:
- commit from release v1.13.3
- commit from release v1.13.4
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 `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