Skip to content

fix(hydrogen): mark cart GET handler responses as personalized - #4344

Open
andguy95 wants to merge 4 commits into
mainfrom
an-cart-private
Open

andguy95 wants to merge 4 commits into
mainfrom
an-cart-private

Conversation

@andguy95

@andguy95 andguy95 commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR: cartHandlers.get() now marks the response as private, so a cached cart response can't be served to other users.

When a loader keeps only the data from cartHandlers.get(), the handler's private cache headers are dropped. The page or React Router .data response then stays cacheable, and a shared cache can hand one user's cart to other users.

Before

const {data} = await cartHandlers.get({storefrontClient});
// the response that renders `data` stays cacheable

After

const {data} = await cartHandlers.get({storefrontClient});
// the request is marked personalized, so applyResponseHeaders() makes the response private

What this changes

  • GET handler: cartHandlers.get() calls markResponseAsPersonalized() before it fetches the cart when the request has a cart ID (cart cookie or cartId search parameter). Marking first covers loaders that stream the cart promise.
  • Public API: requestContext.markResponseAsPersonalized(reason) is now exported, for pages that render a cart from getCart() or from a separate /api/cart request.
  • Next.js example: proxy.ts marks the response when getCartId(request) finds a cart ID. Next sends page headers from proxy.ts before Server Components render, and AppShell reads the cart on its own request context, so the handler's mark never reaches the page. Next makes dynamic pages private by default, but it keeps a Cache-Control header set in proxy.ts, so a merchant's public cache header would apply to a page carrying the buyer's cart ID and key.
  • Docs: JSDoc, README, the Nuxt example, the cart UI skill references (React, Vue, Next.js), the request handlers Next.js reference, and the storefront contract describe the new behavior.
  • Tests: cover document requests, .data requests, reads without a request, no cart ID, an expired cart cookie, and a streamed cart read.

Developer impact

Includes a patch changeset for the handler behavior and a minor changeset for the new public markResponseAsPersonalized().

getCart() doesn't mark the response. Call markResponseAsPersonalized() yourself when:

  • you use getCart() directly
  • a page fetches /api/cart as a separate request (such as Nuxt useFetch)
  • the framework sends response headers before the cart read (such as Next.js proxy.ts)

Out of scope

  • A page cached for a visitor without a cart carries {cart: null}, which tells the client not to fetch /api/cart. A buyer with a cart cookie who gets that cached page sees an empty cart. This predates the PR and will be a follow-up: the client store fetches /api/cart when it gets {cart: null} but the browser has a cart cookie. Vary: Cookie doesn't work here: Oxygen keys on the whole cookie header, so every visitor gets a separate cache entry, and Cloudflare ignores Vary by default.

Risk

  • Any request with a cart ID is no longer cacheable, so origin traffic goes up for those requests. Requests without a cart ID stay cacheable.
  • A cart cookie for an expired or completed cart still makes the response private. That is intentional.

How to Test

  1. Run pnpm build:pkgs, then cd examples/nextjs && pnpm build && pnpm start -p 3417.
  2. Create a cart: curl -si -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Origin: http://localhost:3417' -d '{"action":"add","lines":[{"merchandiseId":"gid://shopify/ProductVariant/43695710371862","quantity":1}]}' http://localhost:3417/api/cart, and copy the cart=… value from set-cookie.
  3. Temporarily add response.headers.set("Cache-Control", "public, s-maxage=60") before requestContext.applyResponseHeaders() in examples/nextjs/proxy.ts, then rebuild and restart.
  4. Run curl -s -o /dev/null -D - -H 'Cookie: cart=<value>' http://localhost:3417/products/slides. Confirm cache-control: private, no-store, max-age=0, must-revalidate.
  5. Run the same request without the cookie. Confirm cache-control: public, s-maxage=60.

@shopify

shopify Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Oxygen deployed a preview of your an-cart-private branch. Details:

Storefront Status Preview link Deployment details Last update (UTC)
Skeleton (skeleton.hydrogen.shop) ✅ Successful (Logs) Preview deployment Inspect deployment November 19, 2026 9:12 PM

Learn more about Hydrogen's GitHub integration.

@andguy95
andguy95 requested a review from fredericoo November 9, 2026 21:37
@andguy95
andguy95 marked this pull request as ready for review November 9, 2026 21:37
@andguy95
andguy95 requested a review from a team as a code owner November 9, 2026 21:37

@fredericoo fredericoo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some caveats with nextjs (headers already sent, so it doesn't matter there)

@andguy95
andguy95 requested a review from fredericoo November 10, 2026 23:18

@fredericoo fredericoo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

left a long comment about the follow-up to get things working as expected. pls work on that so we can release the next version with everything working properly

@andguy95
andguy95 marked this pull request as draft November 13, 2026 22:05
@andguy95
andguy95 marked this pull request as ready for review November 13, 2026 22:46
@andguy95

andguy95 commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator Author

@fredericoo I read the comment and agree. I updated to mark get as personalized with no cartId guard.

Also, a rate-limited GET /api/cart now gets private, no-store, max-age=0, must-revalidate instead of plain no-store, since the private header is applied after the 429 one.

Ill follow up with no2 before merging this one as well

@github-actions

Copy link
Copy Markdown
Contributor

📦 Bundle size report

Status Target Scenario Minified Gzip Δ Minified Δ Gzip
🟡 server cart handlers 23.9 kB 7.14 kB +51 B (+0.2%) +28 B (+0.4%)
🟡 server entry: @shopify/hydrogen 169.53 kB 53.59 kB +51 B (+0.0%) +32 B (+0.1%)
Unchanged (13)
Status Target Scenario Minified Gzip Δ Minified Δ Gzip
⚪ server customer account 22.91 kB 7.17 kB ±0 ±0
⚪ server entry: @shopify/hydrogen/customer-account 25.41 kB 8.29 kB ±0 ±0
⚪ server predictive search handlers 9.32 kB 3.71 kB ±0 ±0
⚪ server request handling 53.8 kB 17.52 kB ±0 ±0
⚪ client entry: @shopify/hydrogen/react 98.18 kB 31.88 kB ±0 ±0
⚪ client entry: @shopify/hydrogen/vue 97.99 kB 31.69 kB ±0 ±0
⚪ client react cart 48.3 kB 15.08 kB ±0 ±0
⚪ client react collection 11.59 kB 3.94 kB ±0 ±0
⚪ client react predictive search 9.39 kB 3.43 kB ±0 ±0
⚪ client react product 14.66 kB 5.23 kB ±0 ±0
⚪ client react shop pay button 10.13 kB 4.45 kB ±0 ±0
⚪ client react shopify scripts 18.66 kB 6.87 kB ±0 ±0
⚪ client vanilla cart 37.44 kB 11.59 kB ±0 ±0
How this is measured

Each scenario is bundled from the built package with Rolldown (tree-shaken, minified, dynamic imports inlined), then gzipped. Peer dependencies are external. Scenarios live in scripts/bundle-size-scenarios.ts.

🟢 smaller · 🟡 larger (< 5%) · 🔴 larger (≥ 5%) · 🆕 not in base · ❌ failed to bundle · ⚪ unchanged

cartHandlers.get() now marks the request context personalized when the request has a cart ID, so applyResponseHeaders() makes the response private and uncacheable. Also exposes markResponseAsPersonalized() publicly and documents it in the cart UI skill references.
Next sends page headers from proxy.ts before Server Components render, and
AppShell reads the cart on its own request context, so the cart GET handler's
mark never reached the page. Next keeps a Cache-Control header set in
proxy.ts, so a public cache header would apply to pages carrying the buyer's
cart ID. Mark the response in proxy.ts when the request has a cart ID, and
update the Next.js skill references and storefront contract.
A page cached for a visitor without a cart carries `{cart: null}`, which tells
`CartProvider` not to fetch `/api/cart`. A buyer with a cart who gets that cached
page sees an empty cart. `cartHandlers.get()` now marks the response personalized
on every call, not only when the request has a cart ID, and the Next.js example
proxy marks every request to match.
The cart GET marks its response personalized before it fetches, and
applyResponseHeaders applies the private value after the 429 no-store, as it
already does for Customer Account requests. The #4282 test asserted plain
no-store for a rate-limited GET, so it now asserts the private value, and the
applyResponseHeaders docs say a marked response keeps it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants