Repository navigation
Conversation
When the cart query returns errors, the cart GET handler returns
{cart: null, errors}. The cart store ignored the errors and showed an
empty cart with no browser load. The store now sets CartState.loadError
for resolved and streamed initial data, and for a full load that fails
before the store has a cart ID. refresh() is the retry. The React Router
template shows a "couldn't load your cart" message with Try again and
hides the cart's lines, totals, and counts while loadError is set.
trackCartAnalytics now updates its baseline when the cart changes
without a new updatedAt, so a retry after an add doesn't make the next
change report existing lines as added.
|
Oxygen deployed a preview of your
Learn more about Hydrogen's GitHub integration. |
|
thanks for digging into this, the diagnosis is spot on and the test coverage is solid. i'd like to hold off on merging this shape though, and go with a different API that we can ship additively in a minor my worry with what i'd rather do is pull the load lifecycle out of useCart(sel) // unchanged: data is always there. loading and readyPromise get deprecated
useCartStatus() // the only place the lifecycle lives:
| { phase: 'loading' }
| { phase: 'ready' } // includes "no cart" (data.id === null)
| { phase: 'failed'; error: CartNetworkEntry; retrying: boolean; retry(): void }plus a <CartReady
loading={<p>Loading cart…</p>}
failed={({ retry, retrying }) => <CartLoadError onRetry={retry} busy={retrying} />}
>
<CartLines />
<CartFooter />
</CartReady>( what this gets us:
a few rules i think it needs:
with this i think none of this needs to break anyone:
|
TL;DR: When the server can't read the cart, for example when the Storefront API throttles the cart query, shoppers saw an empty cart with no checkout button even though their cart still existed. The cart state now reports the failure as
loadError, and the template shows "We couldn't load your cart." with a Try again button.When the cart query returns GraphQL errors,
getCartreturns{cart: null, errors}and the cart GET handler passes both to the root loader.createCartStoreonly readcart, so it treated the failed read as "this shopper has no cart". It settled withloading: falseand empty data, and it never loaded the cart in the browser, because initial data means the server already answered. The shopper's cart and cookie were fine, but the drawer said "Your cart is empty." until the next cart change orrefresh(). StreamedinitialDatadropped the errors the same way.I chose an explicit error state over two alternatives. Throwing from the loader would turn every page into the error page whenever the cart read fails. Retrying in the browser on its own hides the failure from the shopper, and for streamed data it would start a fetch during server rendering.
Before
After
What this changes
loadErroron the cart state. The store sets it when resolved or streamedinitialDatahas anullcart with errors. It also sets it when a full load fails before the store has a cart ID, which covers the first load without initial data and the load afterreset(). It's aCartNetworkEntry, so a non-2xx response keeps itsstatus.refresh()is the retry. The store never retries on its own. A retry that returns the cart, or confirms there is no cart, clearsloadError. A retry that fails replaces it and adds no second network error.reset()from the failed state reloads the cart.loadError. An add from the failed state merges only the added line, sodatacan hold a partial cart until a full load.errors. A{cart: null, errors}response from your cart endpoint now counts as a failed load instead of "no cart".trackCartAnalyticsnow updates its baseline when the cart changes without a newupdatedAt. Without this, a retry that loads the full cart after an add would make the next change report every existing line as added.Developer impact
Includes a minor changeset for
@shopify/hydrogen. Adds the optionalCartState.loadErrorfield. Storefronts that don't read it still show an empty cart after a failed read, as before.Other behavior changes:
store.fetch()now rejects when your cart endpoint returns{cart: null, errors}.reset(), now setsloadErrorinstead of leaving a plain empty state.Docs: TSDoc for
CartState,CreateCartStoreOptions,CartStore.fetch()andCartStore.refresh(), thehydrogen-cart-uiskill (SKILL.md,references/react.md,references/vue.md), and the cart notes in the 2026-10 migration guide. The TSDoc examples now pass the handler's data envelope instead of{ cart: loaderData.cart }, which droppederrors.UX impact
In the React Router template, while
loadErroris set:/cartshow "We couldn't load your cart." with a Try again button. After an add from this state, the message reads "Your item was added, but we couldn't load the rest of your cart."CART_VIEWED.Out of scope
loadErroris set./cartneeds JavaScript.reset()beforeconnect()or during a refresh leaves the cart loading.Risk
trackCartAnalyticschanges for every storefront, not only in the failed state. A cart that changes without a newupdatedAtnow replaces the baseline without publishing events.store.fetch()rejecting for a failed read is new. Code that awaits it now sees the error.How to Test
pnpm install, thenpnpm turbo run build --filter='@shopify/hydrogen-template-react-router^...'.pnpm --filter @shopify/hydrogen-template-react-router devand open the URL Vite prints. Add a product, then open the cart drawer to confirm it's there.templates/react-router/app/root.tsx, temporarily change the loader'scartData: cartResult.data,tocartData: { cart: null, errors: [{ message: "Throttled" }] },and reload./api/cartand click Try again. Confirm "Loading your cart…" appears, then the error again./api/cartand click Try again. Confirm the cart from step 2 appears with its total and Checkout, and the header count comes back./cartand confirm the same failed state. Revert the loader change.I ran this flow in headless Chromium with Playwright against mock.shop. In that run, the failed retry in step 5 came from a route override that answered
/api/cartwith{cart: null, errors}, not from a blocked request.