Upgrade Hydrogen 1 to 2 with Remix

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.

Install the following Hydrogen 2 and Remix packages:

1. @remix-run/react: The primary package for Remix.
2. @shopify/hydrogen@latest: A package that includes tools and utilities built for Remix.
3. @shopify/remix-oxygen: A package for deploying to Oxygen. Alternatively use another adapter if deploying to another environment.
4. @shopify/cli@latest: The Shopify CLI package.
5. @shopify/cli-hydrogen@latest: A package for the Hydrogen extensions to the Shopify CLI.

Remove vite.config.js and remove Vite as a dependency in package.json:

You should no longer see vite in the package.json dependencies.

Add a .env file with variables for the following:

Then remove hydrogen.config.js.

At the root of your project, add a new remix.config.js file with the following content:

1. In the root folder of your project, create a server.js file for Remix. This file is used to create a Storefront API client and Remix request handler. Refer to our server.js in the Hydrogen’s hello world template.

2. In the app directory, add entry.server.jsx and entry.client.jsx.

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.

In your package.json, update the build, dev, and preview commands. The following is an example:

1. Rename and move src/assets to public.
2. Rename the src directory to app.
3. Add global CSS (common to the whole app) to app/styles/app.css.

For instructions on implementing different CSS solutions, refer to Remix's guide on CSS. For example, the documentation includes instructions specific to Tailwind.

Convert index.html into 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 <link>, <meta> or <script> tags. Ignore the Hydrogen v1 script, which points to /@shopify/hydrogen/entry-client. When you're finished, delete index.html.

Rename all routes, removing the .server.jsx suffix. For example, rename routes/index.server.jsx to routes/index.jsx. Remix also follows different conventions for file routes. The following routes need special considerations:

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 useShopQuery and 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.

In Remix, instead of a separate pattern for API routes, loader and 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:

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:

Learn more about 404 handling in Remix here.

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:

If you have TypeScript errors, then update the tsconfig.json and remix.env.d.ts in the root folder. Refer to the tsconfig.json and remix.env.d.ts in the Hydrogen’s hello-world template.

See the Hydrogen guides for the following topics:

• Cart
• Internationalization with Shopify Markets
• Analytics
• SEO