Shopify Hydrogen Migration Checklist: What to Plan Before Going Headless

The React stack is rarely the hardest part of a Shopify Hydrogen migration.

The harder work usually sits elsewhere: Liquid logic built up over years, apps that depend on theme extensions, customer account flows, checkout and domain configuration, redirects, analytics, content ownership, and the editing workflow marketing will use after launch.

Miss those dependencies during discovery and they become expensive implementation changes later.

Before choosing a CMS, storefront starter, or implementation partner, audit the storefront you already have and the team expected to operate the next one.

If Hydrogen itself is still unfamiliar territory, start by understanding how Shopify Hydrogen and Oxygen work.

Shopify Hydrogen migration checklist

Before approving a migration, make sure you can:

1. Define what Liquid is stopping you from doing.
2. Audit your theme, business logic, apps, and content.
3. Confirm a supported headless path for every critical integration.
4. Decide whether Hydrogen is actually the right architecture.
5. Choose between a prebuilt Hydrogen foundation and a bespoke implementation.
6. Estimate work by complexity and dependencies—not page count.
7. Plan SEO, analytics, checkout, accounts, domains, and product feeds.
8. Prepare monitoring, rollback, and post-launch ownership.

If several of those answers are unclear, the migration is not ready to estimate.

1. Start with the reason for leaving Liquid

“Headless will make the site faster” is not a migration brief.

Hydrogen gives teams more control over rendering, routing, caching, data loading, and the storefront experience. Shopify positions Hydrogen and Oxygen as its recommended stack for building headless Shopify storefronts. Hydrogen is a React Router application optimized for Shopify's Storefront API, while Oxygen is Shopify's edge hosting platform.

That flexibility also changes what your team owns.

A Hydrogen storefront is a custom frontend application. Someone has to manage releases, regressions, integrations, monitoring, framework upgrades, and the workflow that keeps the site moving after launch.

A stronger reason to migrate sounds more like this:

• Your theme architecture makes new merchandising experiences slow or risky to ship.
• Product discovery or personalization no longer fits the theme model.
• The storefront needs data from Shopify and several external systems.
• Market, localization, or content requirements have outgrown the current architecture.
• The roadmap requires interactions that are difficult to maintain in Liquid.

Turn that constraint into a measurable outcome. It might be campaign launch time, mobile conversion, engineering hours spent fixing theme regressions, or the cost of entering a new market.

And if the problem can be solved cleanly inside the existing theme, solve it there.

Liquid remains the better choice for many stores. Hydrogen makes sense when additional frontend control is worth the additional ownership. Headless is not automatically faster; the result still depends on architecture, data loading, caching, third-party scripts, media, and implementation quality.

2. Audit the storefront before estimating the rebuild

A mature Shopify theme contains years of business decisions. Some live in Liquid. Others live in JavaScript, metafields, metaobjects, app extensions, tracking scripts, checkout configuration, or undocumented workarounds.

You need to know which of those decisions must survive the migration.

Start by inventorying:

• Templates, sections, blocks, and snippets
• Navigation and search
• Product forms and cart behavior
• Customer accounts
• Checkout configuration and extensions
• Markets and localization
• Metafields and metaobjects
• Structured data
• Analytics and tracking
• Accessibility behavior
• Custom scripts

Then give each item one destination:

• Rebuild
• Redesign
• Replace
• Retire

Do not assume everything deserves to move. A migration is also an opportunity to remove customizations that no longer create enough value to justify their maintenance cost.

Find business logic hiding in Liquid

Audit anything that affects product availability, pricing presentation, discounts, bundles, subscriptions, cart contents, B2B behavior, delivery messaging, or market logic.

The useful question is not simply whether Hydrogen can reproduce the behavior. Ask where that behavior should live next, what data it needs, and who will own it after launch.

Map content ownership

Document where storefront content currently comes from: Shopify fields, metafields, metaobjects, theme settings, a third-party CMS, or hard-coded files. Then document who edits it.

A headless storefront does not automatically need an external CMS. Add one only when its workflow, localization, governance, or cross-channel use justifies another system.

If marketer autonomy is a requirement, evaluate the operating models explicitly: a code-only workflow, Shopify-managed structured content, an external CMS, or a visual editing layer connected to approved Hydrogen components. The right choice depends on governance, localization, preview requirements, and how frequently the team launches campaigns.

3. Treat every app as unverified until proven otherwise

Do not assume an app working with your Liquid theme will work the same way with Hydrogen.

Apps integrated through theme app extensions may rely on Liquid app blocks, app embeds, JavaScript assets, or storefront markup that does not carry over to a Hydrogen storefront. A headless implementation may instead require an API, SDK, web component, vendor-hosted UI, or custom interface.

Build an integration matrix before architecture is approved.

Cover every launch-critical service, including search, reviews, subscriptions, loyalty, personalization, analytics, consent, ERP or PIM systems, localization, tax, fraud, and shipping.

For each vendor, confirm:

• Is the headless integration supported in production today?
• Which APIs, SDKs, and webhooks are required?
• Are there rate limits or authentication constraints?
• Is headless usage included in the current plan?
• Which UI still needs to be built?
• Does the SDK support the Oxygen runtime if you plan to deploy there?
• Who owns failures and maintenance?

Oxygen is a worker-based JavaScript runtime and does not support every Node.js API. Validate runtime compatibility rather than assuming a server-side SDK will work unchanged. See Shopify's Oxygen technical specifications.

“We support headless” is not enough. Ask for implementation documentation and include the integration work in the estimate.

4. Decide what you actually need to build

Once the current storefront and its dependencies are visible, the architecture decision becomes easier.

Liquid is usually the lower-risk option when standard commerce patterns cover most requirements, the existing theme already meets performance and conversion goals, and frontend engineering capacity is limited.

Hydrogen becomes more compelling when differentiated UX is part of the commercial strategy, the storefront needs multiple data sources, market or content requirements have outgrown the theme model, and the business can support a React application after launch.

Then decide how much of the storefront foundation actually needs to be bespoke.

A fully bespoke implementation fits teams with genuinely proprietary UX and the engineering capacity to maintain it. Another option is to begin with a prebuilt Hydrogen storefront foundation, component system, or accelerator and focus custom work on the experiences that differentiate the business.

This distinction matters: a Hydrogen “theme” or starter is not a Shopify Online Store theme and does not use the Liquid theme architecture. It remains a React application that requires deployment, testing, upgrades, and engineering ownership.

That choice can change the project estimate more than many framework-level decisions.

5. Budget for complexity, not page count

Page count is a poor proxy for migration effort.

A storefront with only a few templates can still become complex when subscriptions, B2B pricing, multiple markets, custom accounts, advanced search, or several backend systems are involved.

Estimate the migration by workstream rather than relying on universal price bands:

A useful estimate should state its assumptions, exclusions, dependencies, contingency, and ongoing operating costs.

Oxygen is currently available at no additional charge on supported paid Shopify plans, but hosting is only one part of the operating cost. Recurring cost commonly includes engineering ownership, third-party platform fees, observability, and ongoing integration maintenance. For many teams, engineering remains the largest component. Confirm current plan eligibility in Shopify's Oxygen documentation.

Put dependencies into the timeline

A migration usually involves several overlapping workstreams:

1. Discovery and audit: inventory, integration validation, architecture, and risk.
2. Experience and technical design: journeys, components, content ownership.
3. Build and integration: storefront, accounts, APIs, and analytics.
4. Content and QA: migration, accessibility, performance, and tracking.
5. Launch preparation: domains, redirects, feeds, load testing, and rollback.
6. Stabilization: monitoring and production edge cases.

The exact duration depends on scope. The dependency order matters more.

An unconfirmed subscription API can block cart work. An unfinished content model can block page building. Analytics left until the end can delay launch even when the frontend looks complete.

If coordinated load testing is required, Shopify recommends allowing three to five weeks before go-live so Shopify and other service providers have time to prepare. See Shopify's Hydrogen production checklist.

6. Plan the Shopify-specific migration path

A Hydrogen launch changes more than the page-rendering layer. Confirm how traffic, checkout, carts, accounts, and external channels will behave before cutover.

Domains and checkout

Customers using either Liquid or Hydrogen are directed to Shopify-hosted checkout. Plan the primary storefront domain and the checkout subdomain, then validate analytics, consent, payment methods, extensions, and return paths across both.

Also confirm that Online Store password protection is disabled before launch, because it can prevent Hydrogen checkout from working correctly. Shopify documents these requirements in its online store to Hydrogen migration guide.

Cart continuity

Shopify can preserve carts between the Online Store and Hydrogen through the shared cart cookie. For this to work during migration or rollback, the relevant products must be published to both the Online Store and Hydrogen sales channels.

Test cart restoration, discount behavior, selling plans, buyer identity, localization, and checkout handoff rather than treating “add to cart” as a single acceptance test.

Customer accounts

Choose the account architecture before estimating account pages. Document whether the store will use Shopify customer accounts through the Customer Account API, a legacy customer account flow, or—where relevant—Multipass.

Shopify recommends the Customer Account API for headless customer experiences. Test login persistence across the storefront and checkout, order history, addresses, localization, account-related emails, and B2B buyer identity. Never cache customer-specific API data or personally identifiable information. See Shopify's Customer Account API setup guide.

Product feeds, notifications, and existing orders

When the storefront domain changes, review Meta and Google product feeds, notification URLs, app-generated backlinks, and order-status links for active orders. A frontend that works correctly can still lose advertising traffic or send customers to 404 pages if these dependencies are missed.

7. Plan SEO and analytics before launch

A redesign is not automatically an SEO migration.

Inventory existing URLs, metadata, canonicals, structured data, hreflang, sitemaps, robots rules, internal links, redirects, and current organic performance.

Preserve valuable URLs where possible. Where they must change, use direct server-side redirects and avoid unnecessary chains. Include product, collection, content, account, cart, campaign, app proxy, and legacy order-related URLs in the redirect inventory.

Hydrogen provides utilities and routes for metadata, sitemaps, and robots.txt, but they still need to be configured and validated. Review Shopify's SEO guidance for Hydrogen.

Treat analytics as a data contract too.

Define the events the business depends on before launch, then validate consent, attribution, checkout handoff, third-party pixels, content security policy, and any server-side tracking in the stack.

Do not carry forward an older Hydrogen analytics implementation without review. Shopify deprecated the previous shopify_y and shopify_s cookie-based approach on April 30, 2026. Current migrations should use the supported Hydrogen analytics implementation and validate that events reach Shopify Analytics. See the Hydrogen analytics migration guide and analytics validation guide.

Platform dependencies belong in the same audit.

From January 1, 2027, public apps making Admin API requests must use expiring offline access tokens. This is a public-app dependency, not a general Hydrogen migration requirement, and it does not apply to custom apps or apps created by merchants. Only add it to storefront scope when an affected public app is part of the architecture or your team owns that app. See Shopify's developer changelog.

The same principle applies to Shopify API versions, Hydrogen releases, React Router, and third-party SDKs. Dependency maintenance should be part of the operating plan from the beginning.

8. Decide who runs the storefront after launch

Before production traffic moves, confirm:

• Domains, checkout subdomain, and redirects
• Cart continuity and checkout handoff
• Customer accounts
• Payments, discounts, gift cards, and subscriptions
• Markets and localization
• Search
• Analytics and consent
• Product feeds and notification URLs
• Accessibility and performance
• Monitoring and alerts
• Environment variables and secrets
• Incident ownership
• Rollback procedure

Then answer the harder question:

Who owns the storefront after the implementation team leaves?

Assign responsibility for upgrades, components, performance, vendor failures, analytics, SEO, accessibility, incidents, and releases.

Also define what marketing can change without engineering. A headless storefront can be technically flexible and still create an operational bottleneck if every landing page, campaign, or merchandising change requires a code release.

Evaluate that workflow as an architecture decision. Developers may retain direct control of the React application while merchant teams work through structured Shopify content, a CMS, or a visual editing layer with approved components. The right model should be selected and tested before launch—not added as a workaround afterward.

The go/no-go check

Before approving the migration, your team should be able to say yes to these questions:

• Do we have a measurable reason to move beyond Liquid?
• Have we inventoried the storefront behavior and business logic that matter?
• Does every critical app have a documented, production-supported headless path?
• Do we know where content will live and who will edit it?
• Have we chosen a prebuilt foundation or bespoke build based on actual requirements?
• Does the estimate include integrations, migration, QA, contingency, and maintenance?
• Are checkout domains, carts, accounts, feeds, and notifications covered?
• Does the timeline include SEO, analytics, testing, and stabilization?
• Does marketing have an acceptable editing workflow?
• Are monitoring and rollback ready and tested?
• Does someone own the React storefront after launch?

If several answers are still “not yet,” resolve them during discovery.

Launch week is an expensive place to discover missing scope.

The bottom line

Do not start a Shopify Hydrogen migration with a framework shortlist.

Start with the storefront you already operate: its business constraints, Liquid logic, apps, content, checkout, accounts, integrations, and owners.

Then decide whether those requirements justify Hydrogen.

If they do, the next question is how much of the storefront foundation your team actually needs to build from scratch—and how the business will operate it after launch.

If marketer autonomy is one of the requirements, explore how Weaverse approaches visual storefront building for Shopify Hydrogen while keeping approved React components inside the implementation workflow.

Sources

• Hydrogen and Oxygen fundamentals
• Migrate from the online store to Hydrogen
• Hydrogen production checklist
• Customer Account API: Getting started
• SEO for Hydrogen
• Analytics with Hydrogen and Oxygen
• Migrate Hydrogen analytics tracking
• Validating and troubleshooting analytics with Hydrogen
• Expiring offline access tokens for public apps