Updates

Today we're releasing a developer preview of the new Hydrogen, rebuilt in partnership with Vercel to be framework-agnostic, runtime-agnostic, and built for agents. You can bring Hydrogen to the framework and hosting platform you already use.

Headless commerce has always been about choice. When we released Hydrogen, we leaned into Remix and gave developers a complete, opinionated framework for commerce on Shopify — a framework you adopted as a whole. It was the right call for the moment, and it still powers great storefronts today. But the way developers build kept moving: teams arrive with a framework they love, a runtime they've picked, and, increasingly, a coding agent working alongside them. So we rebuilt Hydrogen to work with what you're using.

The new Hydrogen is a toolkit, not a framework: a framework-agnostic core of Shopify storefront primitives, thin bindings for the framework you're using, and agent skills that teach your coding agent how to wire it all together.

What's new in the preview:

• The core is plain JavaScript, so it works with Next.js, React Router, SvelteKit, Astro, SolidStart, or Nuxt. React bindings ship today; other frameworks use the core primitives directly.
• It runs anywhere you can call fetch: Oxygen, Vercel, Cloudflare Workers, Node, or Deno.
• Agent skills ship with the package and guide your coding agent through building each part of the storefront.
• A typed Storefront API client, with GraphQL written through gql() and results typed against the schema. No codegen.
• Cart, product, and collection primitives, money formatting, Shop Pay, and first-party analytics with consent handling.
• Server-driven cart and request handlers that work before client-side JavaScript loads, with optimistic UI on top.

We'll keep adding to the preview, with more framework bindings, customer accounts, and predictive search on the roadmap.

Our goal

Hydrogen was created as the missing developer toolkit for headless commerce on Shopify — built to let developers focus on building, instead of plumbing. That goal hasn't changed. What's changed is our belief about how best to deliver it.

A framework is a strong opinion about everything: routing, data loading, rendering, deployment. That opinion is a gift when it matches how you want to work, and a tax when it doesn't. As the ecosystem matured, we saw more and more developers who didn't need Hydrogen to make those decisions for them — they'd made them. What they needed was the commerce: a fast, correct, well-typed path to the Storefront API, a cart that's hard to get wrong, analytics that respect consent, and Shop Pay and checkout that convert.

And there's a new builder in the room. More and more storefronts are built with a coding agent, and an agent can scaffold a cart in seconds. But agents tend to get the details that decide whether a store converts wrong: money math that has to match Shopify to the cent, analytics that honor consent, the events apps and checkout depend on. Reinventing those on every build burns tokens and costs sales. They shouldn't be a fresh guess each time; they should come from Shopify, correct by default.

So we pulled commerce out of the framework. The new Hydrogen is the part only Shopify can build — and nothing else.

Framework-agnostic

The heart of the new Hydrogen is a framework-neutral core written in plain JavaScript. On top of it sit thin bindings that make the primitives feel native to your framework. React bindings ship in the preview today; Vue, Svelte, and Remix 3 are on the way.

Creating a typed Storefront API client and querying it looks the same everywhere:

Code Example
Copy
import {
  createStorefrontClient,
  createStorefrontRequestContext,
  gql,
} from "@shopify/hydrogen";

const storefront = createStorefrontClient({
  type: "private",
  config: {
    storeDomain: process.env.PUBLIC_STORE_DOMAIN,
    privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN,
    i18n: { language: "EN", country: "US" },
    buyerIp: getBuyerIp(request.headers), // reads the forwarded client IP
    requestContext: createStorefrontRequestContext(request),
  },
});

const { data } = await storefront.graphql(
  gql(`
    query Home {
      products(first: 3) {
        nodes { handle title }
      }
    }
  `),
);

Because queries are written with gql(), data is typed against the Storefront API schema, so your editor knows the shape of every field and flags errors inline. A gql.tada check step carries the same validation into CI, so a renamed field fails the build instead of slipping through as an empty result.

The cart is reactive in React…

Code Example
Copy
import { createCartComponents } from "@shopify/hydrogen/react";
import type { cartHandlers } from "./cart-handlers";

export const { CartProvider, useCart, useCartForm } =
  createCartComponents<typeof cartHandlers>();

// Re-renders only when totalQuantity changes.
function CartCount() {
  const totalQuantity = useCart((cart) => cart.data.totalQuantity);
  return <span>{totalQuantity}</span>;
}

…or reactive with no framework at all:

Code Example
Copy
import { createCartStore } from "@shopify/hydrogen";

const cart = createCartStore({ initialData });
cart.connect();

cart.subscribe((state) => {
  document.querySelector("#cart-count").textContent =
    String(state.data.totalQuantity);
});

Both share the same idea. The parts of a storefront that change at runtime — the cart, applied filters, the active market, search results — are observables: a small, signals-style reactive model. You subscribe with a selector and your code runs only when that slice changes, so the UI reacts to what actually changed instead of re-rendering everything. In React that's a hook; anywhere else it's a .subscribe() call.

To prove this out, we ported the same storefront to a range of frameworks — Next.js, React Router, SvelteKit, Astro, SolidStart, and Nuxt — and you can browse all of them in the preview repo. They're proof-of-concepts, not starter kits. The path to a real storefront is your framework's own scaffolding plus Hydrogen's skills, which generate code for your stack.

Runtime-agnostic

The core depends on the web platform, not a host. If it can call fetch, it can run Hydrogen. That means you can deploy your storefront wherever it makes sense for your team — Oxygen, Vercel, Cloudflare Workers, Node, or Deno — without losing Shopify's commerce capabilities. One preview caveat: deploying to Oxygen through the Shopify CLI isn't wired up yet.

Hydrogen still takes care of the parts of the request lifecycle that have to be right. A small set of request handlers own the routes your framework's router should never see — the Storefront API proxy, cart endpoints, checkout and cart permalinks, and the MCP and agent proxies that connect your store to agents — and slot into your server before and after routing. Redirects like /admin and Storefront URL redirects run after a 404:

Code Example
Copy
handleShopifyRoutes();     // before your router
// your framework router
handleShopifyRedirects();  // only after a 404
// your framework 404 page

Cart mutations, redirects, analytics tokens, and caching headers are handled for you, server-side, so they keep working even before the page hydrates — and you don't have to reimplement them per runtime.

Built for agents

More and more storefronts are built with a developer and a coding agent side by side, and a toolkit should be legible to both. So we kept the API small enough to fit in a prompt — and we put the instructions where the agent is actually working.

Hydrogen ships with a suite of agent skills — focused, framework-aware guides that are versioned to the exact package you install and copied into your project at setup. They cover setting up the Storefront API client, wiring request handlers, building the cart and cart drawer, collection and search browsing, product pages and variant selection, money formatting, Shop Pay, Markets localization, analytics, and runtime verification.

Because the skills live in your project and match your installed version, your agent works from instructions that are always current — and tuned to how Hydrogen actually wants to be used. No stale blog posts, no guessing at APIs that changed three releases ago.

It goes deeper than generating code. Hydrogen speaks Shopify's standard events and actions — the same commerce contract Liquid storefronts use. Because a headless store and a theme now emit the same events and accept the same actions, an app integrates with either one the same way, and an agent can read your store's state and update the cart through the same interface. The same plumbing that powers your cart drawer is what lets an agent shop your store.

Designed with the Next.js team at Vercel

Building something that's genuinely at home in any framework means designing it with the people who build those frameworks. We redesigned Hydrogen in partnership with the Next.js team at Vercel — pressure-testing the core against a real Next.js App Router storefront, sharpening the boundary between what belongs to commerce and what belongs to the framework, and making sure the primitives feel native rather than bolted on.

The result is a toolkit that respects your framework's conventions instead of fighting them: its routing, its data loading, its server model, its deployment target. Hydrogen brings the commerce; your framework stays in charge of everything else.

Getting started

Getting started takes three steps. First, scaffold a project with your framework's own CLI — here we'll use Next.js:

Code Example
Copy
npx create-next-app@latest

Next, add Hydrogen from your project directory:

Code Example
Copy
npx @shopify/hydrogen@preview setup

This installs @shopify/hydrogen and copies its agent skills into your project, matched to the version you just installed.

Then ask your coding agent to build the storefront:

Code Example
Copy
Can you set up my store with Shopify?

Your agent picks up the installed skills and wires the storefront into your app — the Storefront API client, request handlers, cart, product and collection pages, analytics, and Shop Pay — idiomatically for your framework. Add your PUBLIC_STORE_DOMAIN and your server-only PRIVATE_STOREFRONT_API_TOKEN, start your dev server, and you have a storefront.

Full instructions are in the developer preview documentation.

What's next

This is a developer preview, which means it's a beginning, not a finish line. The API will change, more framework bindings are coming, and capabilities like customer accounts and predictive search are on the roadmap. Current Hydrogen remains fully supported, and the storefronts you're running today keep working exactly as they do now. We'll share migration guidance as the new APIs stabilize.

By pulling commerce out of the framework, we can move faster on the part only Shopify can build and meet developers on whatever stack they choose, with their agents building alongside them.

We'd love your help shaping it. Try the preview, build something real, and tell us where it shines and where it gets in your way in the Shopify developer community.

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.