Reference React components

reference/storefront-react/ is Curobi’s fork-and-restyle React implementation for a headless purchase path and customer portal. It is a starting point you own, not a drop-in widget and not an npm package with a versioning contract.

The directory is deliberately outside the theme extension. A headless storefront should control its own markup, styles, state, and cart integration; it should not inherit a Liquid widget or spend any of the theme extension’s 100 KB budget.

Copy the cart-property helpers exactly, then place a real test order. Cart-line properties have no runtime validation on either side: a misspelled key is indistinguishable from not using the feature, so Shopify completes an ordinary subscription and the intended box pick, Mix & Match grouping, or gift is silently absent.

What is included

Eleven components cover both halves of a headless subscription experience.

Area	Components
Purchase path	Frequency selector, build-a-box builder, Mix & Match picker with live pricing, and gift panel
Customer portal	Portal shell, box editor, reschedule control, line editor, payment method, notification preferences, and cancel flow

The companion modules are worth keeping even if you rewrite every component: properties.ts holds the exact cart-property encodings, and client.ts centralizes the two-credential request headers, standard error envelope, and session refresh behavior.

The purchase components call the Storefront API for the catalog, price preview, gift terms, and the selling_plan_id that a subscription cart line needs. The portal components use the Customer API, after your storefront exchanges the shopper’s Shopify Customer Account API token for a Curobi session.

The deliberate seams

The components emit a CartLineDraft; they do not add a cart line themselves. Hydrogen, Oxygen, Shopify’s Ajax API, and custom storefront backends all add cart lines differently. Keeping that operation in your app means the reference works with each of them without silently choosing a cart architecture for you.

Likewise, the pieces Shopify owns — pause, cancel, skip, and contract-line data — are supplied as props rather than proxied through Curobi. Use Shopify’s Customer Account API for those actions. Curobi owns the subscription-specific behavior around the box, Mix & Match tiers, selection window, save flow, and customer notifications.

The cart-property contract in code

properties.ts encodes the eight property keys used by the purchase components:

Feature	Hidden property	Visible companion
Build-a-box	`_rc_box_pick`	`Your picks`
Mix & Match	`_rc_mm_group`	—
Gift	`_rc_gift`, `_rc_gift_email`, `_rc_gift_start`	`Gift recipient`, `Gift message`

The hidden keys carry machine-readable data. The visible companions are intentional: they let a buyer, merchant, and fulfillment team read the box contents and gift details in the order. Preserve both the spelling and hidden-versus-visible split. For wire formats, required fields, and server-side rules, use Headless & custom storefronts as the source of truth.

Adopt the reference safely

Copy reference/storefront-react/ into your storefront codebase and restyle it for your design system.
Keep properties.ts intact unless you are intentionally updating the documented contract.
Implement the small adapter that converts each CartLineDraft into the cart mutation used by your storefront.
Configure the publishable key and allowed browser origins for the Storefront and Customer APIs.
Place a real order for each feature you offer and confirm its Curobi record: a build-a-box pick, a Mix & Match selection, and a gift subscription.

The reference is typechecked and has tests that pin the property encodings, but your fork is still your integration. Re-run the test orders whenever you change cart code or replace the components.