Developer preview release notes: August 18, 2026

New

Carts can now have session attribution

Cart handlers accept a customerSession. New carts are created with the signed-in customer's buyer identity, and authenticated cart reads mark the checkout URL so shoppers aren't handed a guest checkout.

Pass customerSession to createCartServerHandlers(), then pass those handlers back as cartServerHandlers to createCustomerAccountServerHandlers(). The two stay in step from there: login and token refresh attach the customer to the browser cart; logout, or a refresh that fails for good, detaches them.

Sync never blocks the route's redirect. A failed detach on logout expires the cart cookie instead.

Cart attributes

Cart-level attributes are new: attributes-update is a cart action for order-wide data like a gift message, and form fields register with register("attributeValue", {key}). Line attributes, already accepted on add and update, now come back in cart queries and count toward line identity. The same variant added with different attributes produces separate lines instead of merging into one.

Standard page view events

ShopifyScripts emits shopify:page:view on the first page load and on every client-side navigation, tagged with the page template resolved from your routes. A Hydrogen storefront used to look like a single page load to analytics and performance tooling; it now reports the way a themed store does.

Development builds can load Shopify's standard events inspector to watch the stream. Production builds don't include it.

Storefront ID for cart analytics

createStorefrontClient accepts an optional storefrontId and sends it as a trusted header on Storefront API requests. Cart activity is attributed from the server rather than the browser. On Oxygen, a linked storefront injects the ID as an environment variable.

Custom paths for more Shopify routes

Route templates map Shopify's canonical resource URLs onto the paths your storefront actually serves. Without them, Shopify's redirects and attribution parameters point at URLs you don't have: a cart at /basket gets sent to /cart.

createShopifyRouteTemplates() accepts cart, search, policy, and collectionList alongside the product, collection, page, blog, and article templates. Predictive search suggestions follow the configured search route.

Pluggable logging

configureLogging({level, logger}) sets how much Hydrogen logs and where the logs go. The level runs from trace to fatal, plus silent, and defaults to info. The logger accepts anything with matching level methods, so warnings and errors reach your own observability tooling instead of the console. Console output stays the default, prefixed [hydrogen:<level>:<scope>], for example [hydrogen:warn:cart].

Local HTTPS for Customer Account development

Customer Account OAuth needs an HTTPS origin that isn't localhost, which made login the one flow you couldn't test without a tunnel or your own certificates. Hydrogen uses local.tryhydrogen.dev:5173, a Shopify-owned hostname that resolves to 127.0.0.1.

Vite apps configure it with localHttps() from the new @shopify/hydrogen/vite entrypoint; Next.js uses next dev --experimental-https. Register the origin in your Customer Account API settings. The new hydrogen-local-https skill has the per-framework setup.

Changed

Shopify script traffic goes through your domain

Scripts loaded by ShopifyScripts send their API calls to your domain, which forwards them to Shopify. Resources under /.well-known/ are served from your origin too, so services verifying your customer-facing domain aren't bounced to myshopify.com. There's nothing to configure: handleShopifyRoutes serves the proxy, and ShopifyScripts points the runtime at it.

Checkout, cart permalinks, and Customer Account handoffs are full document navigations now: a client-side router would intercept those server redirects before the request reached your server.

Shop Pay renders locally

The Shop Pay button no longer loads shop-js from Shopify's CDN. It renders as a custom element with styles sealed in a shadow root, so it displays correctly before JavaScript runs. Page CSS can't reach in. renderShopPayButton returns the server HTML, and getShopPayButtonUrl returns the checkout URL on its own.

Styling is limited to width and borderRadius. If your style-src has no 'unsafe-inline', the button stays at its default width: both properties apply as an inline style attribute, which a nonce can't cover.

Cart correctness under concurrent mutations

Overlapping cart mutations could leave totals and quantities wrong. Hydrogen's optimistic cart updates are rebuilt around per-mutation transactions: cancellation is reliable, and an update that gets superseded no longer leaves a stale total on screen.

CartState.revalidating and pending.cost are new, so you can tell a background refresh apart from a pending change and hold totals steady while a cost-affecting mutation settles.

Route handling

handleShopifyRoutes() returns null synchronously when no route matches, and framework routing continues without an async hop. Matched routes still return Promise<Response>.

Responses from handleShopifyRoutes and handleShopifyRedirects come back with the storefront headers Hydrogen requires already applied; if you were setting those headers yourself, remove that code. handleShopifyRedirects also accepts public clients, even ones without a token, since the redirect lookup only queries urlRedirects.

Shopify.navigate is deprecated. Use Shopify.routes.navigate.

Vue parity

The Vue binding gets useCartAnalytics(), matching the React hook. Vue's ShopifyScripts forwards every core option, including shopifyAnalytics, and no longer warns when routes is omitted.

Fixes

The API proxy no longer forwards Cloudflare's client IP header to Shopify, and a redundant client IP header was dropped from Storefront API requests. Locale path prefixes with stray whitespace normalize instead of leaking into resolved URLs. createStorefrontClient autocomplete covers every client type, not just the first overload.

Versioned preview releases

Previews publish through changesets prerelease mode, and version numbers name their target release: 2026.10.0-preview.1 is the first preview of what becomes 2026.10.0.

Agent skills

Two new skills: hydrogen-customer-account for logged-in account pages, and hydrogen-local-https for Customer Account development. The hydrogen-setup skill was reworked into a sequenced walkthrough, and generated projects now recommend the Shopify AI Toolkit.

Removed

• loadShopJs, getShopPayButtonAttributes, and getShopPayButtonStyleProperties are gone, along with the loadScript prop on the React and Vue Shop Pay components.
• buyerIp is no longer accepted in private Storefront client config. Build a request context that carries the buyer IP, createShopifyRequestContext({buyerIp}), and pass that.
• createEmptyPending, CART_API_PATH, CART_GET_METHOD, and CART_POST_METHOD are no longer exported.
• The manual bridge to PerfKit, Shopify's performance monitoring, is gone. PerfKit reads shopify:page:view directly.
• @0no-co/graphqlsp is no longer a direct dependency. The bundled TypeScript plugin covers it.

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 116d5d7ea..d91af14a4