Moving a Liquid store to Hydrogen: the checklist

This checklist assumes the decision is made. If it isn’t, start with when headless pays for itself. The good news about a Liquid-to-Hydrogen move is that the hard data doesn’t move: products, orders, customers and redirects stay in Shopify. The risk is in everything the theme did quietly, which a new storefront has to do on purpose.

1. Inventory what the theme does today

• Templates and URLs. Export every URL pattern that gets traffic: products, collections, pages, blog articles, search, and any custom templates. Hydrogen can use different paths, but each change needs a redirect.
• Sections the team edits. List what merchandisers change without a developer. Each needs a new home, such as metaobjects, metafields or a CMS, and an editing flow someone has tried before launch.
• Apps with a storefront presence. Reviews, search, bundles, loyalty, pop-ups, chat. Anything an app adds as a block or embed in the theme has no theme to live in on Hydrogen: each app needs an API or headless integration, or a replacement.
• Scripts and pixels. Every tag, pixel and snippet in theme.liquid and the theme’s settings, with an owner and a reason to keep it.

2. URLs, redirects and SEO

Hydrogen’s storefrontRedirect utility queries the Storefront API for a redirect created in Shopify for the current path and performs it; if there is none, it passes your response through. The usual pattern is to call it only when the app returns a 404, so redirects managed in the Shopify admin keep working after launch. Two details to test:

• Query parameters are ignored when matching unless matchQueryParams is true. If old URLs carried meaningful parameters, decide which behaviour you want.
• By default /admin redirects to the store’s Shopify admin; noAdminRedirect turns that off.

For metadata, getSeoMeta renders titles, descriptions, canonical URLs, images and JSON-LD into the document head. Hydrogen can generate sitemap routes, which update within a day when content changes, and a robots.txt route cached for 24 hours by default. On Oxygen, robots.txt is only served in the public production environment with a custom domain; preview links get a disallow-all file. If you self-host, you build that protection yourself.

3. Markets and languages

Hydrogen reads the store’s Markets configuration and passes the locale into Storefront API queries, but routing is yours to build: the default locale, the URL scheme, a country selector and any locale detection. Shopify recommends a separate URL for each locale, either as paths (/fr, /es) or as domains; paths have the advantage of needing no domain setup. It also warns against redirecting visitors automatically by detected locale: page caching ignores locale cookies, headers and search parameters, and search engine crawlers may not send them. Keep the existing market URLs where you can, or redirect each one explicitly.

4. Customer accounts

Hydrogen signs customers in through the Customer Account API with OAuth: a login route sends the customer to Shopify, and an authorize route exchanges the token and stores it in the app’s session. Plan for two constraints. The API doesn’t accept localhost, so local development needs an HTTPS tunnel registered in the Shopify admin (callback URI, JavaScript origin and logout URI). And Multipass isn’t supported by the Customer Account API, so a store that relies on Multipass single sign-on needs a different plan.

5. Analytics and consent

Analytics is built into Hydrogen, but Shopify’s guidance is explicit: before you track anything, comply with customer consent rules, either with Shopify’s Customer Privacy API and native cookie banner or with a third-party consent service. Rebuild the tag list from step 1 on top of that consent layer, then check that events arrive in Shopify’s analytics before launch, not after.

6. Caching rules

Hydrogen caches Storefront API requests by default, with CacheShort, CacheLong, CacheNone and custom strategies per query. Customer Account API data is never cached. Anything personalised needs CacheNone on the query and a no-store or private header on the page, so one visitor’s data never lands in a shared cache. Write the rule for each route down; it is also the list your reviewer checks.

7. A baseline to compare against

Before launch, record what the Liquid store does today, so the new storefront is judged against numbers rather than impressions:

• Organic landing pages and their traffic, from Search Console, so any page that drops after cutover is found in days, not months.
• Core Web Vitals by page type, from Shopify’s web performance reports and Search Console.
• Conversion rate and add-to-cart rate by device, from Shopify’s analytics.
• Which apps and tags fire on which page, from step 1, to confirm the same events arrive after launch.

A new storefront often changes several of these at once. With a baseline, you can tell a real regression from normal variation and fix it before it becomes the new normal.

8. Cutover, in order

1. Freeze theme changes a short while before launch, so the URL map and tag list stay true.
2. Deploy the Hydrogen storefront to a private or noindex environment and crawl it: status codes, canonicals, structured data, sitemap.
3. Replay the list of old URLs against it and confirm each returns the page or a single redirect.
4. Test login, logout and order history with a real customer account, and each market’s URLs.
5. Confirm consent and analytics events with a test session.
6. Switch the domain, then watch 404s, Search Console coverage and conversion daily for the first weeks.
7. Keep the Liquid theme unpublished but intact until the new storefront has been stable for a while; it is your rollback.

Where the new storefront runs is its own decision: see Oxygen or self-hosted on Workers.

9. After launch: who owns it

A theme can be left alone for months; a Hydrogen storefront shouldn’t be. Name the person who upgrades dependencies, moves the Storefront API version forward, watches 404s and cache behaviour, and adds new market or app integrations. If nobody is named, the migration isn’t finished. Put the caching rules from step 6 and the URL map from step 2 in the repository, so the next developer inherits the reasoning as well as the code.

How Lintel approaches it

We haven’t published a client Liquid-to-Hydrogen migration, and we won’t pretend otherwise. What exists is Snow / Motion, a Hydrogen storefront on the Storefront API built by Lintel’s founder, and this website, a Hydrogen app with its own redirects, sitemap, noindex previews and cache rules. A migration project with us starts with steps 1 and 2 of this list, delivered as a written plan before any template is built.