Updates

The April release includes two breaking changes to how Hydrogen handles the Storefront API proxy and consent tracking. We've also updated the Storefront API and Customer Account API to 2026-04.

Mandatory Storefront API proxy

The Storefront API proxy is now always enabled. The proxyStandardRoutes option has been removed from createRequestHandler.

Previously, proxyStandardRoutes defaulted to true but could be disabled, and a missing storefront instance in your load context would log a warning:

Code Example
Copy
// Before (v2026.1)
createRequestHandler({
  build,
  getLoadContext,
  proxyStandardRoutes: true, // optional, defaulted to true
});
// Missing storefront in context → console warning, proxy skipped

Now the proxy is always on, and if your load context doesn't include a storefront instance, the request handler throws:

Code Example
Copy
// After (v2026.4)
createRequestHandler({
  build,
  getLoadContext,
  // proxyStandardRoutes is gone — proxy is always enabled
});
// Missing storefront in context → throws Error

If you're using createHydrogenContext() to build your load context, no changes needed. It already provides the storefront instance. If you have a custom getLoadContext that doesn't always return a storefront, you'll need to update it.

Backend consent mode

Hydrogen now sets window.Shopify.customerPrivacy.backendConsentEnabled to true before the Customer Privacy API script loads. This tells the consent library to use server-set cookies via the Storefront API proxy instead of the legacy _tracking_consent JavaScript cookie.

The flag is installed through a property interceptor on window.Shopify that survives the CDN's window.Shopify = {} reset cycle, so it's readable before the full Customer Privacy API is assigned.

If you're using Hydrogen's ShopifyCustomerPrivacy component (or the analytics provider that wraps it), this is automatic. There's no new config to set. The old _tracking_consent cookie path is being deprecated in favor of this server-side approach.

Other changes

For the full list of API-level changes, including a 128KB limit on JSON metafield writes and a new MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR cart error code, see the Storefront API 2026-04 changelog and Customer Account API 2026-04 changelog. The full release notes also cover a fix to React Router peer dependency ranges.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.

The Hydrogen January 2026 release (v2026.1.0) updates the Storefront API and Customer Account API to 2026-01. This is a quarterly API version bump with no Hydrogen-specific feature changes.

Review the Storefront API 2026-01 changelog and Customer Account API 2026-01 changelog for details on what changed at the API level, including a now-required discountCodes argument on the cartDiscountCodesUpdate mutation. See the full release notes on GitHub for the complete list.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.

Welcome to the October release! This one adds new cart mutations that cut down on the client-side state juggling required for gift cards and delivery addresses. We've also updated the Storefront API and Customer Account API to 2025-10.

Add gift card codes without re-submitting existing ones

Previously, applying a new gift card code meant reading the codes already on the cart and passing the full list back through cart.updateGiftCardCodes. With cart.addGiftCardCodes, you can append codes directly:

Code Example
Copy
const result = await cart.addGiftCardCodes(['SUMMER2025']);

The skeleton template has been updated to use this new mutation. If you forked the skeleton, here's the pattern. A CartForm posts a single giftCardCode field, and the route action wraps it into an array:

Code Example
Copy
// app/components/CartSummary.tsx
function AddGiftCardForm({children}: {children: React.ReactNode}) {
  return (
    <CartForm
      route="/cart"
      action={CartForm.ACTIONS.GiftCardCodesAdd}
    >
      {children}
    </CartForm>
  );
}

// app/routes/cart.tsx
case CartForm.ACTIONS.GiftCardCodesAdd: {
  const formGiftCardCode = inputs.giftCardCode;
  const giftCardCodes = (
    formGiftCardCode ? [formGiftCardCode] : []
  ) as string[];

  result = await cart.addGiftCardCodes(giftCardCodes);
  break;
}

Replace all delivery addresses in one call

cart.replaceDeliveryAddresses swaps every delivery address on a cart in a single mutation, replacing the old pattern of deleting existing addresses and re-adding new ones:

Code Example
Copy
const result = await cart.replaceDeliveryAddresses([
  {
    address: {
      deliveryAddress: {
        address1: '123 Main St',
        city: 'Anytown',
        countryCode: 'US',
      },
    },
    selected: true,
  },
]);

Also available as CartForm.ACTIONS.DeliveryAddressesReplace.

Other changes

The @inContext directive now accepts an optional visitorConsent parameter for encoding buyer consent preferences into the cart's checkoutUrl. This is intended for Checkout Kit and other non-Hydrogen integrations that manage consent outside Shopify's standard flow. If you're using Hydrogen's analytics provider, you don't need it.

For the full list of API-level changes in Storefront API 2025-10, see the Storefront API changelog and Customer Account API changelog. The full release notes on GitHub cover everything in this release.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.

Our latest release delivers major improvements to the Hydrogen toolkit, adding support for the Storefront API 2025-07 and updating key dependencies like React Router 7.9.2 and Miniflare v3.

With this release, we’re making sure it’s clear which configurations are supported out of the box by pinning to specific versions of dependencies by default in the provided package.json file. You can still update or enable different RR7 feature flags, but note that those paths might introduce breaking changes.

This release also makes vibe coding with Hydrogen even better, and includes 10 new ways to easily extend and customize your build. We’ve replaced the set of static feature templates with new additions to the Hydrogen Cookbook, adding new recipes for use cases like working with metaobjects, using infinite scroll for pagination, building for B2B, and more.

Here’s the full breakdown of everything included in this release:

React Router 7 updates

Hydrogen is now up to date with the latest version of React Router, which means developers can now get access to two big benefits:

1. Route Module Type Safety: React Router now automatically generates route-specific types to power type inference for URL params, loader data, and more.
2. Middleware: Middleware lets you run code before and after the Response generation for the matched path. This enables common patterns like authentication, logging, error handling, and data preprocessing in a reusable way.

To start using middleware and working with the new context object format in React Router, we’ve added a createHydrogenContext helper and a HydrogenRouterContextProvider type to make integrating with Hydrogen simple.

For full details on React Router, refer to the v7.9.2 changelog.

Miniflare v3

Local development has been upgraded to use Miniflare v3, based on workerd. Hydrogen’s CLI already used a workerd runtime (unlike Miniflare v2), so you won’t see any changes to your local development workflow—but if you had seen deprecation warnings about Miniflare v2, those are now gone.

Storefront API 2025-07 support

• USDC currency support: The Money component and useMoney hook have been updated, adding support for USDC.
• Hydrogen’s default scaffold now has improved order filtering support, letting customers filter their orders by fulfillmentStatus.
• For full changes to the GraphQL APIs, refer to the Customer Accounts API and Storefront API changelogs.

Hydrogen Cookbook updates

The --template flag has been removed from the init command, and our previous Example templates have now been replaced with individual recipes in the Hydrogen Cookbook.

We’ve added new Cookbook recipes for:

• B2B
• Customer cart methods
• Express
• GTM
• Infinite scroll
• Legacy customer account flow
• Markets (improved)
• Metaobjects
• Partytown
• Third-party APIs

Updates, optimizations, and fixes

As always, this release includes additional optimizations, bug fixes, and quality-of-life improvements.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.