In server.ts call createCartHandler with storefront and getCartId / setCartId callbacks; getCartId reads the cart ID from a cookie (or session), setCartId writes it back on the response headers
The handler returns a cart object with methods: cart.get(), cart.addLines(), cart.updateLines(), cart.removeLines(), cart.updateDiscountCodes(), and others — call these in Remix action functions
Create a cart.tsx route (or an action in root.tsx) with a Remix action that reads a formData action field to dispatch the correct cart mutation (for example, 'add-line', 'remove-line')
In the action call await cart.addLines([{ merchandiseId, quantity }]) and return the response using cart.setCartId inside a redirect or json response so the updated cart cookie is propagated
In the root loader call cart.get() to fetch the current cart and pass it to the Outlet context; components subscribe to cart state via useCart() or useMatches()
Ensure the CartProvider from @shopify/hydrogen is wrapping the app root for client-side optimistic cart updates if you use the built-in cart components
Known gotchas
setCartId must be called on every response that modifies the cart, including errors — if you forget it on an error branch the cart cookie becomes stale and the customer loses their cart
createCartHandler depends on the Storefront API cart mutations; if your Hydrogen version and the Storefront API version are mismatched, method signatures may differ — align versions explicitly in package.json
The cart handler uses Storefront API cart mutations internally; large carts with many line items can hit Storefront API rate limits — implement debounce on rapid quantity-increment UIs
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