Upgrade Hydrogen 1 to 2 with Remix
Introduction
Anchor 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 packages
Anchor 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 Vite
Anchor link to section titled "Step 2: Remove Vite"Remove vite.config.js
and remove Vite as a dependency in package.json:
You should no longer see vite
in the package.json
dependencies.
Step 3: Set up local dev environment variables
Anchor link to section titled "Step 3: Set up local dev environment variables"Add a .env
file with variables for the following:
Then remove hydrogen.config.js
.
Step 4: Create a Remix config
Anchor 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 file
Anchor link to section titled "Step 5: Create a server file"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 ourserver.js
in the Hydrogen’s hello world template.In the
app
directory, addentry.server.jsx
andentry.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.
Step 6: Update package.json scripts
Anchor link to section titled "Step 6: Update package.json scripts"In your package.json
, update the build
, dev
, and preview
commands. The following is an example:
Step 7: Move public assets
Anchor link to section titled "Step 7: Move public assets"- Rename and move
src/assets
topublic
. - Rename the
src
directory toapp
. - 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.
Step 8: Set up a root route
Anchor link to section titled "Step 8: Set up a root route"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
.
Step 9: Rename all routes
Anchor link to section titled "Step 9: Rename all routes"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:
Hydrogen 1 | Hydrogen with Remix |
---|---|
robots.txt.server.js | [robots.txt].jsx |
sitemap.xml.server.ts | [sitemap.xml].jsx |
products/[handle].server.jsx | products/$handle.jsx |
policies/[handle].server.jsx | policies/$handle.jsx |
collections/[handle].server.jsx | collections/$handle.jsx |
pages/[handle].server.jsx | pages/$handle.jsx |
journal/[handle].server.jsx | journal/$handle.jsx |
Step 10: Remove useShopQuery
and useQuery
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 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.
Step 11: Convert API Routes
Anchor link to section titled "Step 11: Convert API Routes"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:
Step 12: Add a 404 page
Anchor 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 implementation
Anchor 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 Typescript
Anchor link to section titled "Troubleshooting Typescript"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: