Install @shopify/hydrogen-react and initialize ShopifyProvider with your storeDomain, storefrontApiVersion, and storefrontToken at the app root.
Use the CartProvider component to wrap your app; it manages cart state via React context and handles cartCreate, cartLinesAdd, cartLinesRemove, and related mutations automatically.
Access cart state and actions via the useCart hook: cartId, lines, totalQuantity, linesAdd, linesRemove, discountCodesUpdate, and others.
For Hydrogen (full-stack Remix framework), use server-side cart actions via the cart API helpers in Hydrogen rather than client-side CartProvider to support progressive enhancement.
Configure environment variables SHOPIFY_STORE_DOMAIN, SHOPIFY_STOREFRONT_ACCESS_TOKEN, and SHOPIFY_STOREFRONT_API_VERSION in Oxygen (or .env locally).
Consult the current @shopify/hydrogen-react changelog to confirm which Storefront API version is required for each hook and component.
Known gotchas
@shopify/hydrogen-react and the full @shopify/hydrogen Remix framework have overlapping but different APIs; ensure you are using the correct package for your architecture (React-only vs Remix full-stack).
Cart persistence across sessions relies on storing the cart ID in a cookie or localStorage; the default Hydrogen template uses a server-side session; review the session strategy before customizing.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp