Upgrade Hydrogen 1 to 2 with Remix
IntroductionAnchor link to section titled "Introduction"
Hydrogen is a set of tools, utilities, and best-in-class examples for building a commerce application on top of Remix.
Because Hydrogen is inherently coupled to the Storefront API, we have also decided that Hydrogen will follow calendar versioning. This means that there is no Hydrogen 2.0. Instead the next version of Hydrogen will be 2023.1.0 and moving forward new versions of Hydrogen will be released at the same time as new versions of the Storefront API.
This guide teaches you how to migrate from an existing Hydrogen 1 project. Since each project is different, your migration experience might require additional steps, but you can use this guide as the basis for migrating your app. Before starting your migration, consider reviewing the Remix docs to understand the basics about how Remix apps work.
Step 1: Install Hydrogen 2 and Remix packagesAnchor link to section titled "Step 1: Install Hydrogen 2 and Remix packages"
Install the following Hydrogen 2 and Remix packages:
@remix-run/react: The primary package for Remix.
@shopify/hydrogen@latest: A package that includes tools and utilities built for Remix.
@shopify/remix-oxygen: A package for deploying to Oxygen. Alternatively use another adapter if deploying to another environment.
@shopify/cli@latest: The Shopify CLI package.
@shopify/cli-hydrogen@latest: A package for the Hydrogen extensions to the Shopify CLI.
Step 2: Remove ViteAnchor link to section titled "Step 2: Remove Vite"
vite.config.js and remove Vite as a dependency in package.json:
You should no longer see
vite in the
Step 3: Set up local dev environment variablesAnchor link to section titled "Step 3: Set up local dev environment variables"
.env file with variables for the following:
Step 4: Create a Remix configAnchor link to section titled "Step 4: Create a Remix config"
At the root of your project, add a new
remix.config.js file with the following content:
Step 5: Create a server fileAnchor link to section titled "Step 5: Create a server file"
In the root folder of your project, create a
server.jsfile for Remix. This file is used to create a Storefront API client and Remix request handler. Refer to our
server.jsin the Hydrogen’s hello world template.
Unless you need to customize the streamed response from the server, or add customizations before the front-end hydrates, you shouldn’t need to modify these two files.
Step 6: Update package.json scriptsAnchor link to section titled "Step 6: Update package.json scripts"
package.json, update the
preview commands. The following is an example:
Step 7: Move public assetsAnchor link to section titled "Step 7: Move public assets"
- Rename and move
- Rename the
- Add global CSS (common to the whole app) to
Step 8: Set up a root routeAnchor link to section titled "Step 8: Set up a root route"
app/root.jsx. You can use our sample
root.jsx as a starting point. You'll need to update the document with whatever custom root elements are in your
index.html, such as custom
<script> tags. Ignore the Hydrogen v1 script, which points to
/@shopify/hydrogen/entry-client. When you're finished, delete
Step 9: Rename all routesAnchor link to section titled "Step 9: Rename all routes"
Rename all routes, removing the
.server.jsx suffix. For example, rename
routes/index.jsx. Remix also follows different conventions for file routes. The following routes need special considerations:
|Hydrogen 1||Hydrogen with Remix|
Step 10: Remove Anchor link to section titled "Step 10: Remove useShopQuery and useQuery"
Remix doesn't use React Server Components. This means that you can't fetch data directly within your route components. Instead, all data fetching should be moved into an exported loader function on each route, or within the
root.jsx loader for any data that needs to be globally available.
Move every instance
useQuery in your code into an associated loader.
You can access the data queried within the loader with
useLoaderData(). Shopify provides an API client in the loader context to make querying easier. The following is an example:
Needs to change to:
Read more about data fetching in Hydrogen.
Step 11: Convert API RoutesAnchor link to section titled "Step 11: Convert API Routes"
In Remix, instead of a separate pattern for API routes,
action functions serve as the same purpose — routes are their own API. Hydrogen 1 uses API routes primarily for use cases like creating a
sitemap.xml route. The following is an example converted sitemap route:
Step 12: Add a 404 pageAnchor link to section titled "Step 12: Add a 404 page"
Hydrogen v1 handled 404 pages with a wildcard route defined in
App.server.jsx. Remix also needs a wildcard route; in Remix, these are called "Splat Routes" (learn more).
Add a splat route file at
app/routes/$.jsx. Replacing the route contents with the following code:
Because the route only throws a 404 response, make sure to add a CatchBoundary to
root.tsx. This boundary renders whenever an error is thrown within the app.
Refer to the demo store CatchBoundary for a more complete example.
Also make sure to update any route that takes a parameter, like the collection or product page, to throw a 404
Response if the resource does not exist:
Step 13: Convert session implementationAnchor link to section titled "Step 13: Convert session implementation"
When previously creating the server.ts file, it included an example session implementation. Update the session according to your app needs.
useSession is no longer available. Instead access the session from the request context:
Whenever you make changes to the session, make sure to commit the changes while setting a new cookie header. The following is an example:
Troubleshooting TypescriptAnchor link to section titled "Troubleshooting Typescript"
See the Hydrogen guides for the following topics: