What Works (and Breaks) in Hydrogen: App Compatibility Guide

Introduction

Hydrogen storefronts unlock React-first flexibility — but they also disrupt Shopify’s long-standing app ecosystem. Many apps built for Liquid themes don’t “just work” in Hydrogen. Developers must know which categories are plug-and-play, which need wrappers, and which should be avoided entirely.

This post provides a compatibility guide for apps and plugins in Hydrogen builds.

Categories of App Behavior

1. Works Out-of-the-Box (API-First Apps)

• Subscription services with GraphQL/REST APIs.
• Search + personalization apps that expose SDKs.
• Loyalty platforms with webhook/event APIs.

👉 Example: Recharge Subscriptions → Hydrogen-ready via Storefront API hooks.

2. Needs Wrappers or Middleware

• Reviews apps (e.g., Yotpo, Judge.me) → often inject Liquid snippets.
• Wishlist apps → rely on DOM manipulation in Liquid.
• Fix: Wrap their APIs with custom components.

import { useEffect, useState } from "react"; function ReviewsWidget({ productId }) { const [reviews, setReviews] = useState([]); useEffect(() => { fetch(`/api/reviews?product=${productId}`) .then((res) => res.json()) .then(setReviews); }, [productId]); return <ReviewsList reviews={reviews} />; }

3. Breaks in Hydrogen (DOM-Injection Apps)

• Apps that rely on Liquid section injection (pop-ups, upsells, custom DOM widgets).
• Example: “Insert after </body>” scripts.
• Hydrogen has no Liquid DOM → these apps fail.

👉 Workarounds:

• Replace with API-driven equivalents.
• Build custom React components that replicate functionality.

Example Compatibility Matrix

App Category	Works OOTB	Needs Wrappers	Breaks in Hydrogen
Subscriptions	✅	—	—
Reviews	—	⚠️	—
Loyalty	✅	—	—
Wishlist	—	⚠️	—
Pop-ups / DOM hacks	—	—	❌
Personalization	✅	—	—

Best Practices for Developers

• ✅ Audit app stack before migrating from Liquid → Hydrogen.
• ✅ Ask vendors if they support API-first integrations.
• ✅ Use middleware (Next.js API routes, Firebase Functions) to wrap legacy APIs.
• ✅ Avoid DOM-injection apps → replace with React-native equivalents.
• ✅ Maintain a living compatibility matrix for team + client.

Case Study: Health Brand Migration

• Started with Liquid stack → 15 apps.
• On Hydrogen:
  • 8 apps worked out-of-the-box (subscriptions, loyalty, analytics).
  • 5 needed wrappers (reviews, wishlists).
  • 2 (pop-ups, custom upsell widgets) were replaced entirely.
• Result: leaner app footprint, faster pages, more stable stack.

Conclusion

Hydrogen disrupts the old “just install it” mindset. Developers must carefully assess which apps survive the migration, which need wrappers, and which to replace.

In Hydrogen, compatibility isn’t assumed — it’s engineered.