Migrate from Shopify Liquid to Hydrogen

Moving from a Liquid-based Shopify theme to a Hydrogen headless storefront is a significant architectural shift. Done right, it unlocks better performance, full design control, and long-term scalability. Done poorly, it can tank your search rankings and break existing customer flows. This guide walks through a practical migration path that protects what you have built while upgrading to a modern stack.

Before writing a single line of Hydrogen code, document everything your Liquid store depends on:

• All page templates, sections, and snippets currently in use.
• Third-party apps and scripts injected into the theme (reviews, upsells, popups, tracking pixels).
• URL structure for products, collections, pages, and blog posts.
• Custom Liquid logic for promotions, metafield-driven content, or conditional rendering.

This inventory becomes your migration checklist. Every feature listed needs a Hydrogen equivalent or a deliberate decision to drop it.

URL changes are the biggest SEO risk in any migration. Shopify Liquid stores use paths like /products/handle and /collections/handle. If your Hydrogen storefront changes these patterns, you need 301 redirects for every indexed URL.

• Export all indexed URLs from Google Search Console before migration.
• Match every old URL to its new Hydrogen equivalent.
• Implement redirects at the server or edge level, not with client-side JavaScript.
• Keep the same URL structure wherever possible to minimize redirect dependency.

Avoid rewriting everything at once. Prioritize pages by traffic and revenue impact:

1. Product pages — these drive the most revenue and organic traffic.
2. Collection pages — critical for category-level SEO and browsing.
3. Homepage and landing pages — high visibility, brand-critical.
4. Blog and content pages — important for informational search traffic.
5. Cart and account pages — functional pages with lower SEO impact.

Many Shopify apps inject scripts directly into Liquid themes. These will not work in a headless storefront. For each app, decide whether to:

• Use the app vendor's headless SDK or API if available.
• Build the feature natively in your Hydrogen frontend.
• Find an alternative service that supports API-based integration.

Common areas that need replacement include product reviews, loyalty programs, wishlists, and personalization engines.

Beyond redirects, make sure these elements carry over correctly:

• Page titles and meta descriptions for every template.
• Structured data (Product, BreadcrumbList, Organization).
• Canonical tags and hreflang attributes if multilingual.
• Open Graph and Twitter Card meta tags for social sharing.
• Internal link structure — review with our Hydrogen SEO checklist.

Deploy your Hydrogen store to a staging URL and run thorough checks:

• Compare page-by-page with the Liquid store for content parity.
• Validate all Storefront API queries return correct data.
• Run Lighthouse audits and compare Core Web Vitals against the existing store.
• Test checkout flow end-to-end including payment and order confirmation.
• Verify analytics and conversion tracking fire correctly.

For deployment specifics, see our guide on deploying Hydrogen on Oxygen.

Switch DNS or proxy configuration to point to your Hydrogen storefront. Immediately after launch:

• Submit the updated sitemap to Google Search Console.
• Monitor crawl errors, indexation drops, and ranking changes daily for the first two weeks.
• Watch real-user performance metrics through your analytics platform.
• Keep the Liquid store accessible internally as a rollback option for at least 30 days.

For platform-level implementation details, use the official docs: Hydrogen and Storefront API.