Hydrogen developer preview

Hydrogen is Shopify's framework for building headless storefronts. It provides commerce primitives like cart, products, collections, and a typed Storefront API client, so you can build a fast headless storefront backed by Shopify.

This developer preview is the next version of Hydrogen. It keeps the same commerce primitives but removes the tie to React Router, so you can build with any JavaScript framework and deploy to any JavaScript runtime. It comes with skills that coding agents use to build storefronts.

Anchor to How this preview differs from current HydrogenHow this preview differs from current Hydrogen

Use current Hydrogen if you want Shopify's fully supported path for building with React Router. Use the developer preview to build with Hydrogen's commerce primitives in any JavaScript framework.

Anchor to RequirementsRequirements

The developer preview requires:

• A server-rendered JavaScript storefront, built with the framework of your choice.
• Node.js and npm installed.
• Storefront API access for the store you want to connect. To create a storefront and manage your credentials, use the Headless channel.

Anchor to Get startedGet started

The fastest way to get started is to deploy a starter template. If you'd rather use a different framework or runtime, or add Hydrogen to an existing project, set it up in your own project instead.

Anchor to Deploy a starter templateDeploy a starter template

Pick the template that matches your framework. Each one comes ready to deploy to a managed host.

React Router

Hydrogen + Oxygen

Next.js

Hydrogen + Vercel

Anchor to Set up in your own projectSet up in your own project

Use this path to build with any JavaScript framework, or to add Hydrogen to an existing project. The developer preview is built for coding agents. It ships with skills, focused instructions that teach an agent how to build each part of a storefront, so the agent you already use can set most of it up for you.

Create a project with the framework you want, then add @shopify/hydrogen@preview:

npx create-react-router@latest my-store
cd my-store
npx @shopify/hydrogen@preview setup

npx create-next-app@latest my-store
cd my-store
npx @shopify/hydrogen@preview setup

npx sv create my-store
cd my-store
npx @shopify/hydrogen@preview setup

npm create nuxt@latest my-store
cd my-store
npx @shopify/hydrogen@preview setup

npm init solid@latest my-store
cd my-store
npx @shopify/hydrogen@preview setup

The setup command installs the developer preview package and copies the skills into your project's agent skills folder. Then open your project in the coding assistant of your choice and ask it to build your storefront:

The agent picks up the skills and uses them to set up the Storefront API client, build the cart, and create your product and collection pages.

To connect your storefront to your Shopify store and pull in your products, add your store credentials to your project's environment:

Find these values in the Headless channel for your store.

Then start your dev server (for example, npm run dev) and open your storefront. You should see your products and a working cart.

Anchor to What's includedWhat's included

The preview includes the commerce primitives you need to build a storefront:

• A typed Storefront API client.
• Cart, product, and collection primitives.
• Money formatting.
• First-party analytics with consent handling.
• Shop Pay buttons.
• Request handlers that proxy the Storefront API, cart, and redirects.
• Support for Shopify standard storefront events and actions.
• Predictive search, with route handlers and framework bindings.
• Customer accounts with login, profile, and order history.

Anchor to How it worksHow it works

Hydrogen's commerce logic is written in plain JavaScript, with no framework required. Framework bindings are a thin layer on top.

Anchor to The Storefront API clientThe Storefront API client

Create a request-scoped client on the server, then query it with typed gql() documents:

request is the incoming request from your framework's server handler. getBuyerIp is a small helper you write to read the forwarded client IP from its headers. How you get the request and its headers depends on your platform. The request context carries the cookies, headers, buyer IP, and localization that keep analytics and caching correct. Because the query is written with gql(), data comes back fully typed against the Storefront API schema.

Anchor to Request handlersRequest handlers

A small set of request handlers own the routes your framework's router shouldn't touch, like the Storefront API proxy, cart endpoints, and redirects. They run in your server around your framework's router:

Anchor to The cartThe cart

Load the Standard Actions runtime once in your root document, before wiring the cart:

You create a cart, connect it, and subscribe to it. Then you can read or update the cart from anywhere in your code. React and Vue come with bindings: a provider and hooks for React, a provider and composables for Vue. Other frameworks use the same core primitives directly. Here's reading the cart count in each:

import {createCartComponents} from '@shopify/hydrogen/react';
import type {cartHandlers} from './cart-handlers';

// Create your typed cart components once.
const {CartProvider, useCart} = createCartComponents<typeof cartHandlers>();

// Read a slice of the cart anywhere; re-renders only when totalQuantity changes.
function CartCount() {
  const totalQuantity = useCart((cart) => cart.data.totalQuantity);
  return <span>{totalQuantity}</span>;
}

// Mount the provider once, with the cart fetched on the server.
export function App({initialCart, children}) {
  return <CartProvider initialData={initialCart}>{children}</CartProvider>;
}

'use client';

import {createCartComponents} from '@shopify/hydrogen/react';
import type {cartHandlers} from './cart-handlers';

// Next.js uses the same React bindings.
const {CartProvider, useCart} = createCartComponents<typeof cartHandlers>();

function CartCount() {
  const totalQuantity = useCart((cart) => cart.data.totalQuantity);
  return <span>{totalQuantity}</span>;
}

<script>
  import {createCartStore} from '@shopify/hydrogen';
  import {readable} from 'svelte/store';
  import {onMount} from 'svelte';

  const cart = createCartStore({initialData});

  // connect() is browser-only, so run it after mount.
  onMount(() => cart.connect());

  // Wire the core store into a Svelte store.
  const totalQuantity = readable(cart.getState().data.totalQuantity, (set) =>
    cart.subscribe((state) => set(state.data.totalQuantity)),
  );
</script>

<span>{$totalQuantity}</span>

<!-- Mount <CartProvider> once in your app root, with the cart fetched on the server. -->
<script setup lang="ts">
import {createCartComponents} from '@shopify/hydrogen/vue';
import type {cartHandlers} from './cart-handlers';

// Create your typed cart components once.
const {useCart} = createCartComponents<typeof cartHandlers>();

// Read a slice of the cart anywhere; the ref only updates when totalQuantity changes.
const totalQuantity = useCart((cart) => cart.data.totalQuantity);
</script>

<template>
  <span>{{ totalQuantity }}</span>
</template>

import {createCartStore} from '@shopify/hydrogen';
import {createSignal, onMount} from 'solid-js';

function CartCount() {
  const cart = createCartStore({initialData});
  const [totalQuantity, setTotalQuantity] = createSignal(cart.getState().data.totalQuantity);

  // Wire the core store into a Solid signal after mount.
  onMount(() => {
    cart.connect();
    cart.subscribe((state) => setTotalQuantity(state.data.totalQuantity));
  });

  return <span>{totalQuantity()}</span>;
}

import {createCartStore} from '@shopify/hydrogen';

const cart = createCartStore({initialData});

// Listen for cart mutations from your UI, third-party apps, and agents.
cart.connect();

// Update the DOM whenever the cart changes.
cart.subscribe((state) => {
  document.querySelector('#cart-count').textContent = String(state.data.totalQuantity);
});

Anchor to Framework examplesFramework examples

The preview ships a runnable example of the same storefront in each framework, so you can see how the primitives fit:

• Next.js
• SvelteKit
• Nuxt
• Astro
• SolidStart
• React Router

Anchor to SkillsSkills

The preview includes skills that guide coding agents through building each part of a storefront. They're part of the package, so they stay aligned with the version you install, and the setup command copies them into your project's agent skills folder.

They cover the full storefront:

To see what each skill does, refer to the skills in the project repo.