Hydrogen developer preview

Today we're releasing a developer preview of the new Hydrogen, rebuilt from the ground up in partnership with Vercel, to be framework-agnostic, runtime-agnostic, and built for agents. For the first time, 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 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 already love, a runtime they've already picked, and, increasingly, a coding agent working alongside them. So we asked a simpler question — what if Hydrogen met you where you already are?

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

Here's a quick look at what's new in the preview:

• Framework-agnostic: The core is plain JavaScript. Use it with Next.js, React Router, SvelteKit, Astro, SolidStart, Nuxt — or anything that can run server code. React bindings ship today; Vue, Svelte, and Remix 3 bindings are coming soon.
• Runtime-agnostic: Anywhere you can call fetch, Hydrogen runs. Deploy to Oxygen, Vercel, Cloudflare Workers, Node, or Deno — your choice.
• Built for agents: Hydrogen ships with a suite of agent skills, versioned to the package you install, that guide your coding agent through building each part of a storefront in the stack you already have.
• A typed Storefront API client: Write GraphQL with gql() and get results typed against the Storefront API schema — no codegen step to babysit.
• Commerce primitives, not plumbing: Cart, product and collection primitives, currency-correct money formatting, Shop Pay, and first-party analytics with consent handling.
• Progressive by default: Server-driven cart and request handlers that work without client-side JavaScript, with optimistic UI on top.

Throughout the preview, we'll keep adding to this — including packaged bindings for more frameworks, and tooling forcustomer accounts and predictive search.

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 already 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 a fast path to Shop Pay and checkout.

And there's a new builder in the room. More and more storefronts are built with a coding agent at the keyboard, and an agent can scaffold a cart in seconds. But the details that decide whether a store converts are exactly the ones it tends to get wrong — money math that has to match Shopify to the cent, analytics that honor consent, the events that apps and checkout depend on. Reinventing those on every build burns tokens and quietly 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,
    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 — your editor knows the shape of every field and flags a wrong one 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);
});

Under both is 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 moved instead of re-rendering the world. In React that's a hook; anywhere else it's

.subscribe()

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 real path to a storefront is your framework's own scaffolding plus Hydrogen's skills, generating code tailored to you.

Runtime-agnostic

The core depends on the web platform, not a host. If it can call fetch, it can run Hydrogen. That means you're free to deploy your storefront wherever it makes sense for your team — Oxygen, Vercel, Cloudflare Workers, Node, or Deno — without trading away 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
Request
  → 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 an interface it already understands. 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 favorite 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.

The Future of Hydrogen

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, meet developers on whatever stack they choose, and make the easy way the right way — for the developers building storefronts and the 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 over in GitHub Discussions. This is just the beginning.