Joy on Hydrogen & Weaverse
Bring Joy Loyalty to your Shopify Hydrogen or Weaverse storefront — the floating loyalty widget, the full Loyalty Page and Weaverse blocks, all powered by the same programs you manage in Joy admin.
Headless storefronts are available on the Ultimate plan.
Overview
If your store runs on Shopify Hydrogen (with or without Weaverse), Joy's theme app extensions can't reach your storefront. The Joy headless packages fill that gap: your customers get the same loyalty experience as on an Online Store theme, and you keep managing everything — programs, rewards, VIP tiers, translations and widget branding — from Joy admin.
With Joy on Hydrogen you get:
- The loyalty widget — the floating launcher and panel, showing points, tier, ways to earn and rewards. Customers redeem rewards and the coupon is applied to their cart automatically.
- The Loyalty Page — your Loyalty Page V2 rendered natively in a Hydrogen route, or dropped onto any page as a Weaverse block.
- Signed-in customer data — customers who log in through the Customer Account API see their own balance and rewards, securely.
- Server rendering — the widget paints on the first page load instead of popping in later.
The packages
| Package | What it is for |
|---|---|
@joy-loyalty/hydrogen | The widget, the Loyalty Page, the token route and server helpers for Hydrogen. Every install needs it. |
@joy-loyalty/weaverse-hydrogen | Joy blocks for Weaverse Studio. Install it only on Weaverse storefronts. |
@joy-loyalty/sdk | A framework-agnostic client for the Joy headless API. You only need it to build a fully custom UI. |
Before you start
- Make sure your store is on the Ultimate plan.
- In Joy admin, go to Settings > Developers and turn on Enable Custom Storefront development.
- Set up Customer Account API login in your Hydrogen project. Without it, every shopper is treated as a guest.
- To use the Loyalty Page, switch to Loyalty Page V2 in Joy admin.
Choose your path
- With an AI coding agent (recommended) — your agent follows our step-by-step skill, adapts the code to your project and verifies it with you. You only handle secrets and the deploy.
- Manually — follow the foundation guide, then add the parts you need: the widget, the Loyalty Page or Weaverse blocks.
Install with an AI agent (recommended)
Using the older joyso-hydrogen-sdk package? See Integrate the Joy Loyalty widget to Hydrogen. New installs should use @joy-loyalty/hydrogen.