Weaverse blocks

Register the Joy blocks in your Weaverse Hydrogen storefront so you can build your loyalty page visually in Weaverse Studio.

Overview

@joy-loyalty/weaverse-hydrogen adds a Joy — Loyalty Page block to Weaverse Studio. Drag it onto any page to show your whole Loyalty Page V2, or a single section of it. The block loads its own data, so you don't need a separate Hydrogen route.

Step 1: Install the package

npm i @joy-loyalty/weaverse-hydrogen

Step 2: Register the blocks

In app/weaverse/components.ts:

import {joyComponents} from '@joy-loyalty/weaverse-hydrogen';
 
export const components: HydrogenComponent[] = [
  // ...your existing components
  ...joyComponents,
];

joyComponents contains the Joy — Loyalty Page block (joy-loyalty-page). Its Content setting is either All sections (the full page) or one section: Hero banner, Sign-up banner, How it works, Ways to earn, Ways to redeem, VIP tiers, Referral program, FAQs, Rewards redemption, My rewards, Rewards activity, Loyalty dashboard, Referral management, Loyalty pass wallet or Link accounts.

Optional: in-page launcher block

The package also exports a Joy — Loyalty Launcher block (JoyLoyaltyWidget). It isn't in joyComponents; register it yourself only if you want a launcher you place per page in Studio:

import {joyComponents, JoyLoyaltyWidget} from '@joy-loyalty/weaverse-hydrogen';
 
export const components: HydrogenComponent[] = [...existing, ...joyComponents, JoyLoyaltyWidget];

Most stores use <JoyWidget/> in the root layout instead (see Loyalty widget). Don't use both, or customers see two launchers.

Step 3: Give the blocks your cart

Weaverse blocks can't reach your cart on their own. Wrap your page content in <JoyProvider> so redeemed coupons apply to the cart and your drawer opens:

import {JoyProvider} from '@joy-loyalty/hydrogen';
 
<main>
  <JoyProvider cart={cart ?? undefined} onCartUpdated={syncCartStore} onOpenCartDrawer={openCartDrawer}>
    {children}
  </JoyProvider>
</main>

Without the provider, the block falls back to the cart in your root loader data, then loads /cart itself.

Step 4: Expose the environment to Weaverse

The block loaders read JOY_API_URL, JOY_SHOP_DOMAIN and (optionally) JOY_WIDGET_ASSET_URL from weaverse.env. Make sure these variables are in your .env and Oxygen environments and are passed through to Weaverse. If they are missing, Studio shows "Set the JOY_API_URL and JOY_SHOP_DOMAIN..." in place of the block.

Step 5: Content Security Policy for Studio

Start from your Weaverse CSP lists and concatenate the Joy lists to each, so both Weaverse Studio and Joy are allowed:

const weaverseCsp = getWeaverseCsp(request, context);
const joyCsp = joyCspDirectives({apiUrl: context.env.JOY_API_URL, assetUrl: context.env.JOY_WIDGET_ASSET_URL});
 
createContentSecurityPolicy({
  ...weaverseCsp,
  scriptSrc: [...weaverseCsp.scriptSrc, ...joyCsp.scriptSrc],
  connectSrc: [...weaverseCsp.connectSrc, ...joyCsp.connectSrc],
  styleSrc: [...weaverseCsp.styleSrc, ...joyCsp.styleSrc],
  imgSrc: [...weaverseCsp.imgSrc, 'https://cdn.shopify.com', ...joyCsp.imgSrc],
  fontSrc: [...weaverseCsp.fontSrc, ...joyCsp.fontSrc],
  shop: {/* checkoutDomain, storeDomain */},
});

Also exclude Weaverse preview requests (weaverseHost, isDesignMode, __revisionId and similar parameters) from full-page caching — see Deploy and verify.

Step 6: Build the page in Weaverse Studio

1. Open Weaverse Studio and go to the page you want — for example a new Rewards page.
2. Add the Joy — Loyalty Page block.
3. In Content, choose All sections to show the full Loyalty Page, or pick one section.
4. Publish. Point the widget's loyaltyPageUrl at this page.

Related

• Loyalty Page — the same page as a plain Hydrogen route
• Troubleshooting