Skip to main content

Migrate from Hydrogen v1 to v2

The recommended method for upgrading from Hydrogen v1 to is to create a new Hydrogen project and transfer required features and assets manually.

Key differences between Hydrogen v1 and Hydrogen v2​

  • Hydrogen now uses Remix as its foundational framework. Remix promotes server-side rendering, web standard technologies, and principles of progressive enhancement to boost site performance. Hydrogen provides a collection of components, utilities, and design patterns that make it easier and more performant to work with Shopify APIs.
  • Hydrogen no longer uses React Server Components. Use Remix loader functions instead.
  • Since version 2023.1, Hydrogen has been calendar versioned. This keeps Hydrogen's features in sync with Shopify's API versioning.

To quickly get up to speed on Remix, we recommend completing its 30-minute introductory tutorial.

Routes​

Remix uses nested routes to define the site path.

Hydrogen's default Skeleton template includes all of Shopify's standard storefront routes. When setting up a new Hydrogen project, select the option to "scaffold routes and core functionality" to set up these routes autoatically.

You can also scaffold routes after the fact by using the Hydrogen CLI:

# Run in your new Hydrogen project
npx shopify hydrogen generate routes

For reference, this table compares some typical Hydrogen v1 route files with their Remix equivalents. However, we don't recommend creating every file manually; the generate routes command is the most reliable method to create consistent results.

Hydrogen v1Hydrogen with Remix
index.htmlroot.jsx
robots.txt.server.js[robots.txt].jsx
sitemap.xml.server.ts[sitemap.xml].jsx
products/[handle].server.jsxproducts.$handle.jsx
policies/[handle].server.jsxpolicies.$handle.jsx
collections/[handle].server.jsxcollections.$handle.jsx
pages/[handle].server.jsxpages.$handle.jsx

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.

404 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.

A standard 404 route is generated when setting up a new Hydrogen project if you opt to scaffold the standard routes. Consult the Skeleton template's 404 route file on GitHub if you want to set it up yourself.

Moving static assets​

Remix features two directories that can contain static assets:

  1. public is for static files that should be uploaded directly to Shopify's CDN without being processed by Vite. Files in this directory will be available relative to the site root when deployed. You can hard-code their paths in site files.
  2. app/assets is for static files that will be imported in your site files and will be processed by Vite. File names may be hashed and the files themselves may be optimized or bundled during the build process.

CSS​

Remix uses Vite for bundling and optimization, so all of Vite's standard CSS methods are available in Hydrogen.