Next.js example: three storefront clients aligned with use cache

[malewis5]

What

Splits the Next.js example's single storefront client into three purpose-built clients, each documented against a specific Next.js use cache boundary.

Client	Location	Token	use cache story
getStorefrontClient	app/lib/storefront.ts	private (per-request)	Reads headers() → not cacheable. Use use cache: private for buyer cart / logged-in customer data.
sharedRateLimitStorefrontClient	app/lib/storefront.ts	private (shared rate limit)	No request-time APIs → cacheable with use cache. For non-personalized product / collection / blog pages.
publicStorefrontClient	app/lib/public-storefront.ts	public (per-IP)	Browser-safe. For client-side fetches (predictive search, "load more", availability polling).

Why

Next.js 16's use cache and use cache: private directives draw a hard line between request-time and cacheable data. A single client that always reads headers() can never enter a use cache boundary. Separating the clients by their data-access pattern lets each route reach for the right one — and surfaces, for the core @shopify/hydrogen package, the distinction between buyer-IP, shared-rate-limit, and public token usage.

Changes

• Add app/lib/public-storefront.ts — browser-safe public client.
• Add sharedRateLimitStorefrontClient to app/lib/storefront.ts for use cache-able server fetches.
• Document the use cache / use cache: private boundary on each client with links to the Next.js docs.
• Update README to reference both the server and browser-safe clients.

🤖 Generated with Claude Code

[frandiox]

Thank you Matt! We'll review your PRs and merge soonish, then build on top of your changes 🙏

[andguy95]

This adds/edits the /apps/lib which is moved out in #3810 / #3811. So if those get merge we need to rebase/update path for this PR.

[fredericoo]

just one note: we should refrain from calling graphql straight from the browser, so the public client actually has not a lot of use right now (I think)

but this is the right implementation! we created the three clients with this in mind, glad you instantly got it

[malewis5]

just one note: we should refrain from calling graphql straight from the browser, so the public client actually has not a lot of use right now (I think)

but this is the right implementation! we created the three clients with this in mind, glad you instantly got it

Agree. Tbh only created it to demonstrate private_shared_rate_limit is the right client for server side queries that you can cache.