Developer preview release notes: July 8, 2026

This developer preview update adds Storefront API caching, a Customer Account API, predictive search, typed routing, and storefront tooling for in-browser AI agents, plus a round of changes that unify how requests, carts, and analytics are handled.

New

Subrequest caching for the Storefront API

You can now cache Storefront API responses for catalog data (products, collections, and pages) at the edge and serve repeat visits from the cache. Caching is opt in per query. It's built for Oxygen and other edge runtimes that expose a cache store and a waitUntil hook, which keeps the runtime alive long enough to finish cache writes after the response is sent. The cache layer also accepts a get/set interface for Node.js and other platforms that don't expose a Web Cache API.

• Opt in per query with client.graphql(QUERY, { cache: Cache.long() }). createFetchWithCache() and createRunWithCache() are also available for custom caching of other APIs.
• Built-in strategies: Cache.short, Cache.long, Cache.none, or a custom mix of maxAge, staleWhileRevalidate, and staleIfError. Adapters ship for both the Web Cache API and KV stores. A Cache-Status header reports whether each response was a hit, miss, or stale.
• Caching is opt in, so nothing is cached unless you ask. Mutations and private cache mode are refused, and customer data is never cached.

WebMCP: storefront tools for AI agents

WebMCP lets a storefront expose tools to AI agents running in the browser, so an agent can search the catalog, browse, view a product or variant, update the cart, start checkout, and view orders. Cart actions use Standard Actions.

The tools load by default through ShopifyScripts (opt out with webMcp={false}), or call initializeShopifyScripts() yourself for frameworks without a Hydrogen binding. The script is delivered from Shopify's CDN and injected automatically, so you don't install or import it. It only activates in browsers that expose model-context APIs.

Customer Account API support

This release adds a typed Customer Account API client, for logged-in experiences like order history and profile pages. It lives on its own entrypoint, @shopify/hydrogen/customer-account, with its own gql() and generated schema and types.

createCustomerSession() handles login, the OAuth callback, refresh, and logout. It's framework-neutral and ships default route handlers that plug into handleShopifyRoutes.

Personalized account and session responses are marked private, no-store automatically, so customer data can't land in a shared or CDN cache.

Predictive search

Predictive search gives you same-origin autocomplete. The browser calls your origin (/api/predictive-search), and your server runs the Storefront API predictiveSearch query, so the public storefront token stays server-side.

• Register createPredictiveSearchServerHandlers() (defaults to GET /api/predictive-search), drive it with createPredictiveSearchStore(), which handles debounce, aborts, and stale responses, and consume it through React hooks like usePredictiveSearch and usePredictiveSearchForm.
• getPredictiveSearchItemUrl() builds result URLs that keep Shopify's attribution parameters intact.
• You build the dropdown UI. It degrades to a plain GET /search?q= form when JavaScript isn't available.

Standard routes and redirects

A typed route manifest lets your app describe its URL structure once and reuse it for redirects and predictive-search URLs. This matters when your paths don't match Shopify's defaults, for example /productos/camisa instead of /products/camisa, where Shopify's redirects and attribution parameters would otherwise point at the wrong URL.

createShopifyRouteTemplates() maps Shopify-standard resource locations (products, collections, pages, blogs, articles) onto your app's real paths, and keeps attribution and redirect behavior consistent across the two.

Cart server route handlers

createCartServerHandlers() returns cartHandlers.get() and cartHandlers.post() that register into handleShopifyRoutes, so cart routes use the same registration model as everything else and work the same across frameworks. It replaces the old framework-specific shopifyCartGet bootstrap helper.

ShopifyScripts for SSR runtime tags

ShopifyScripts renders the Shopify browser runtime's <script> and <link> tags plus the window.Shopify bootstrap (preconnects, country/locale/routes globals, Standard Actions, and optionally WebMCP) in one place, instead of hand-wiring those per framework. Use getShopifyScriptTags() / renderShopifyScriptTags() for framework-agnostic setups, or the ShopifyScripts component in React.

Deploy buttons

Generated starters now include deploy buttons for Oxygen and Vercel in their README.

Changed

Unified Shopify request context

There's now a single request context, createShopifyRequestContext, that you reuse for the Storefront client, the Customer Account client, sessions, and handleShopifyRoutes. Everything in a request shares the same headers, locale, and cache policy.

• i18n on the request context now only carries the language and country codes common to both APIs. pathPrefix is optional routing metadata.
• requestContext is now required by the Storefront client, the Customer Account client, session methods, and handleShopifyRoutes, and handleShopifyRoutes must receive the same object as the Storefront client. This is a migration step if you're on an earlier dev-preview.

Typed carts, end to end

Pass a typed gql cart fragment to createCartServerHandlers({ fragment }) and derive typed React bindings with createCartComponents<typeof cartHandlers>(). Cart state types come from your handler definition instead of being written by hand.

Cart initial data can be a promise

Cart initialData now accepts a Promise as well as a resolved payload, so you can return a loader promise directly and let the store hydrate when it resolves. Bindings no longer fire a second fetch. This works with deferred and streaming loaders.

Product forms

React product forms can register an add-to-cart submit button with register("addToCart"), which keeps the button name from drifting and wires submission to the cart store.

Normalized option state exposes Storefront API option value swatches at option.values[n].swatch, so you can render merchant-provided color and image swatches instead of styling from the label text.

Build

React components are now marked "use client", so they import directly into server components without a hand-written client wrapper. GraphQL query strings are minified at build time, so they ship smaller.

Framework examples

Refreshed the framework starter examples, including customer-account login and logout flows for React Router and Next.js.

Agent skills

Updated the skills that ship with the package (product pages, search and collection browsing, cart, analytics, and query validation). Added new skills and refreshed the rest.

Removed

• createStorefrontRequestContext. Renamed to createShopifyRequestContext. No alias is kept.
• shopifyCartGet bootstrap helper. Use cartHandlers.get() from createCartServerHandlers() instead.
• country and language on the analytics consent config. Pass the resolved market to ShopifyScripts or getShopifyScriptTags({ i18n }) instead.
• The WebMCP export from @shopify/hydrogen/cdn. WebMCP now loads from Shopify's CDN through ShopifyScripts or initializeShopifyScripts().
• Request-local in-flight cache dedupe. Concurrent cold misses now run independently. The per-request dedupe made stale-while-revalidate and stale-if-error behavior hard to reason about for little gain.

Migration

For migration guidance, compare the commits that bracket this release. The diff shows the changes between the previous preview and this release:

Code Example
Copy
git diff 0c3bff8fd..8a708a87f