Install with an AI agent (recommended)

Let your AI coding agent install Joy Loyalty on your Weaverse storefront end to end — packages, environment, the Joy blocks, the widget, deploy and verification — while you keep control of the secrets and the deploy button.

Overview

Adding Joy to a Weaverse storefront touches several places: packages, server environment variables, a token route, the root loader, Content Security Policy for Weaverse Studio, caching rules, the Weaverse block registry and your cart. None of it is hard, but it is easy to miss one step.

So we packaged the whole procedure as an agent skill. Your coding agent (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI — any agent that reads Markdown skill files) follows the same step-by-step playbook our own team uses, reads your project, adapts the code to your routes and cart, and then verifies the result with you.

You stay in charge of the three things an agent should never do on its own: handling your headless secret, setting production environment variables, and pressing deploy.

Before you start

Make sure you have:

• Joy Loyalty installed on your Shopify store, on the Ultimate plan.
• Custom storefront development enabled: Settings > Developers > Enable Custom Storefront development.
• A working Weaverse storefront (for example the Pilot theme) with Customer Account API login set up — without it every shopper is treated as a guest.
• Loyalty Page V2 turned on (Joy admin > On-site content > Loyalty page).
• An AI coding agent open in your Weaverse project folder.

Step 1: Add the Joy skill to your project

Run this in your project root:

npx skills add tinhnv2001/joy-loyalty-hydrogen-skills

The command detects which coding agents you use and installs the joy-headless-install skill for each of them. You only do this once per project.

Step 2: Ask the agent to install Joy

Copy one of these prompts into your agent.

Install Joy on Weaverse:

Use the joy-headless-install skill to install Joy Loyalty on this Weaverse Hydrogen storefront.
Register the Joy blocks so I can build my loyalty page in Weaverse Studio,
and add the floating loyalty widget to every page.
Wire both to my existing cart so redeemed coupons apply automatically.
Ask me for any value you need and do not deploy anything.
When you are done, walk me through the verification checklist.

Already installed and something is wrong:

Use the joy-headless-install skill to diagnose my Joy Loyalty integration on Weaverse.
Symptom: <describe what you see, e.g. the Joy block is empty in Weaverse Studio>.

Step 3: Give the agent your Joy values

The agent will ask for these. Here is where to find each one:

Step 4: Review what the agent changed

Before you commit, ask the agent for a summary of its changes. You should see:

• package.json — @joy-loyalty/hydrogen and @joy-loyalty/weaverse-hydrogen added.
• .env and env.d.ts — JOY_API_URL, JOY_SHOP_DOMAIN, JOY_API_SECRET. The .env file must stay out of git.
• app/routes/api.joy-token.ts — the route that signs customers in to Joy.
• app/root.tsx — Joy data in the root loader, <JoyWidget/> in the layout, and <JoyProvider> around the page content.
• app/entry.server.tsx — Joy domains added on top of your Weaverse Content Security Policy, logged-in pages marked private, no-store, and Weaverse Studio previews kept out of the page cache.
• app/weaverse/components.ts — the Joy components registered.

If something on this list is missing, ask the agent why — sometimes your project already handles it, sometimes a step was skipped.

Step 5: Add the block in Weaverse Studio

Once the code is in, build your page: open Weaverse Studio, add the Joy — Loyalty Page block and publish. See Loyalty Page block.

Step 6: What you do yourself

• Add JOY_API_URL, JOY_SHOP_DOMAIN and JOY_API_SECRET in Shopify admin > Hydrogen > your storefront > Storefront settings > Environment variables, for both Preview and Production. Mark JOY_API_SECRET as secret.
• Commit the code (without .env).
• Deploy with shopify hydrogen deploy or your GitHub integration — deploy to Preview first.
• Run the verification checklist below on the preview URL, then promote to production.

Step 7: Verify the installation

As a guest (incognito window):

• The loyalty launcher appears on every page — only one launcher.
• The browser console shows no Content Security Policy errors mentioning joy.so.
• Your loyalty page built in Weaverse shows the guest sections (ways to earn, rewards, VIP tiers).
• The Sign in button goes to your login page.

As a logged-in customer:

• The widget and the block show the customer's real points balance and tier — compare with the customer in Joy admin.
• Redeem a reward: the coupon is applied to the cart and your cart drawer opens.
• Log out: the widget returns to the guest view.

In Weaverse Studio:

• The Joy — Loyalty Page block shows your Loyalty Page, not a "Set the JOY_API_URL…" message.

If every box is ticked, you are live.

Common problems

More fixes: Troubleshooting. Still stuck? Contact us through the in-app chat with your storefront URL and a screenshot of the browser console.

Prefer to do it by hand?

The agent follows the same steps documented in Install manually.