Hydrogen developer preview

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.