Hydrogen

Hydrogen is Shopify’s toolkit for building custom storefronts on the Storefront API. It provides the Storefront API client, the cart, products, collections, search, customer accounts, analytics, and Shop Pay. The developer’s framework determines where the storefront deploys, such as Oxygen (opens in a new tab), Shopify’s hosting platform for storefronts, or Vercel (opens in a new tab). The source code is in the Shopify/hydrogen (opens in a new tab) repository.

Hydrogen has two version lines with different exports:

• Hydrogen 2026-10 is an SDK that the developer adds to an app in an existing framework.
• Hydrogen 2026-04 and earlier is a full-stack framework on Remix or React Router.

Never mix Hydrogen 2026-10 exports with exports from Hydrogen 2026-04 or earlier in one project.

Stay in the hydrogen topic for any storefront that uses Hydrogen or that the developer wants to build with Hydrogen. Use the storefront-graphql topic only when the developer asks for Storefront API calls without Hydrogen.

Choose the version

Choose the version before you search or write code. The version you choose replaces any version that a tool response suggests.

Package versions 2026.10.0-preview.1 through 2026.10.x are Hydrogen 2026-10. Earlier package versions map to the Hydrogen version with the same year and month. For example, 2026.4.7 is Hydrogen 2026-04, and 2025.5.1 is Hydrogen 2025-05.

Read the developer’s package.json, lockfile, and imports first. Then use the first rule that matches:

1. The developer asks to upgrade or migrate without naming a target version, and the project is on Hydrogen 2026-04 or earlier. Find the project’s version with rules 2 through 6. Use Hydrogen 2026-10, and follow the migration steps in the Hydrogen 2026-10 section.
2. The developer names a Hydrogen version or package version, such as 2026-04 or 2026.4.7. Use the Hydrogen version that the name maps to.
3. package.json lists @shopify/hydrogen. Use the Hydrogen version that the installed package version maps to. When package.json gives a range, read the installed version from node_modules/@shopify/hydrogen/package.json or the lockfile. If you can’t read either file, ask the developer which version is installed.
4. package.json lists @shopify/hydrogen-react without @shopify/hydrogen. Use the Hydrogen version that the installed @shopify/hydrogen-react version maps to, and import only from @shopify/hydrogen-react.
5. The code imports from @remix-run/react or virtual:remix/server-build, together with @shopify/hydrogen or @shopify/remix-oxygen. Use Hydrogen 2025-04.
6. The code imports from @shopify/remix-oxygen, or imports CartForm or Image from @shopify/hydrogen. Use Hydrogen 2026-04. When you can’t read package.json, ask the developer for it before you write code.
7. The project uses Next.js, Nuxt, Astro, SvelteKit, or SolidStart. Use Hydrogen 2026-10.
8. The developer names the Image, Video, ExternalVideo, MediaFile, Money, RichText, Pagination, or CartForm component, or an Analytics.* component, and asks how to use the component. Use Hydrogen 2026-04. Questions about the Storefront API Image, Video, and ExternalVideo types don’t match this rule.
9. No rule matches. Use Hydrogen 2026-10.

Search the developer documentation for the chosen version to find similar examples. THIS IS IMPORTANT. Then write complete code that uses only the chosen version’s exports, and explain which Hydrogen exports the code uses.

Hydrogen 2026-10

Hydrogen 2026-10 works in any framework that runs server code, such as Next.js, React Router, Nuxt, Astro, SvelteKit, or SolidStart. Write UI, routing, and data loading in the developer’s framework. Use Hydrogen for the Storefront API client, the cart, products, collections, search, customer accounts, money formatting, analytics, Shop Pay, and the Shopify routes that every storefront needs, such as /api/cart. Serve the Shopify routes with handleShopifyRoutes. The hydrogen-request-handlers skill shows how.

• Imports: Import core functions from @shopify/hydrogen. In React components, including React islands in Astro, import components and hooks from @shopify/hydrogen/react. In Vue components, import components and composables from @shopify/hydrogen/vue. In other UI frameworks, build the UI on core functions such as createCartStore. Import customer account features from @shopify/hydrogen/customer-account. For local HTTPS in a Vite project, import the localHttps plugin from @shopify/hydrogen/vite. Import Storefront API types from @shopify/hydrogen/storefront-api-types, and Customer Account API types from @shopify/hydrogen/customer-account-api-types.
• Removed exports: Hydrogen 2026-10 doesn’t export the Image, Video, ExternalVideo, MediaFile, Money, RichText, Pagination, or CartForm components, the Analytics object and its components, or the getSeoMeta function.
• Storefront API client: Create the client with createStorefrontClient({type, requestContext, config}), and pass the result of createShopifyRequestContext as requestContext. Follow Query the Storefront API (opens in a new tab). To type and validate queries, follow Type and validate Storefront API queries (opens in a new tab).
• Analytics: In React and Vue apps, render the ShopifyScripts component from @shopify/hydrogen/react or @shopify/hydrogen/vue in the root layout. In other frameworks, including Astro, render the tags on the server with renderShopifyScriptTags, and call initializeShopifyScripts in the browser. Read the hydrogen-analytics skill, and follow Add analytics and consent (opens in a new tab).
• Money and images: Format money with formatMoney and the hydrogen-money skill. Render images with an <img> element or the framework’s image component, and size them with the hydrogen-image skill.
• Docs: Pass version 2026-10 to the docs search. Use the Hydrogen 2026-10 reference (opens in a new tab) and the Hydrogen guides (opens in a new tab). Skip pages under https://shopify.dev/docs/storefronts/headless/legacy.
• Setup: To add Hydrogen to an existing project, run npx @shopify/hydrogen@latest setup in the folder that contains package.json. The command installs @shopify/hydrogen and copies Hydrogen’s skills into .claude/skills/ and .agents/skills/. Then follow the hydrogen-setup skill to wire Hydrogen into the app. Follow Add Hydrogen to an existing project (opens in a new tab).
• Skills: Before you write code for a feature, read the skill for that feature, such as hydrogen-cart-ui for a cart UI. If a project on Hydrogen 2026-10 is missing the skills, run npx @shopify/hydrogen skills sync. To update a project on Hydrogen 2026-10, update @shopify/hydrogen to the latest 2026.10 release, and then run npx @shopify/hydrogen skills sync.
• New storefronts: Shopify maintains the React Router template, which deploys to Oxygen. Vercel maintains Vercel Shop, a Next.js template that deploys to Vercel. Use Vercel Shop when the developer asks for Next.js or Vercel. Use the React Router template when the developer asks for React Router or names no framework. Follow Deploy a template (opens in a new tab). For any other framework, create the app with the framework’s own tool, and turn on server rendering, such as with an Astro server adapter. Then run the setup command in the app’s folder. Without a store, ask the developer to run npx @shopify/hydrogen@latest setup in an empty folder in their own terminal and choose the React Router storefront. When the command can’t show its menu, it installs only the skills.
• Examples: The Hydrogen examples directory (opens in a new tab) has examples for Next.js, Nuxt, Astro, SvelteKit, and SolidStart. For React Router, read the React Router template (opens in a new tab). The examples aren’t starter kits. Don’t copy code from examples/hydrogen, which imports @shopify/hydrogen-react version 2026.4.
• mock.shop: Without a store or a Storefront API access token, build against mock.shop, a public Storefront API with mock catalogs. In .env, set PUBLIC_STORE_DOMAIN to a mock.shop host such as pets.mock.shop, and leave PUBLIC_STOREFRONT_API_TOKEN commented out. If the framework needs a prefix for browser variables, add the prefix to each name, such as NEXT_PUBLIC_STORE_DOMAIN in Next.js. Create the client with type: 'public', and set publicStorefrontToken to the token variable. The token stays undefined while its line in .env is commented out. The client rejects an empty token, and mock.shop rejects any token. mock.shop doesn’t support customer accounts or a real checkout. Follow Use mock.shop (opens in a new tab).
• Migration: To move a storefront from Hydrogen 2026-04 or earlier, follow Migrate to the latest version of Hydrogen (opens in a new tab). Update @shopify/hydrogen to the latest 2026.10 release and reinstall the dependencies as the guide describes. Then run npx @shopify/hydrogen skills sync, and follow the migrate-to-hydrogen-2026-10 skill. Write the new code with Hydrogen 2026-10 exports only.

Hydrogen 2026-04 and earlier

Hydrogen 2025-04 and earlier runs on Remix. Hydrogen 2025-05 through 2026-04 runs on React Router.

• Hydrogen React projects: When package.json lists @shopify/hydrogen-react without @shopify/hydrogen, import everything from @shopify/hydrogen-react. Manage the cart with CartProvider and useCart, and send analytics with sendShopifyAnalytics. Use the framework’s own routing and server code. Pass the chosen version to the docs search. For versions earlier than 2025-07, pass 2025-07, and keep the imports from the installed @shopify/hydrogen-react package. Use the Hydrogen React 2026-04 reference (opens in a new tab), and replace 2026-04 in the URL with the version that you passed to the search. The other bullets in this section apply only to projects that list @shopify/hydrogen.
• Imports: Import components such as Image, Money, and CartForm from @shopify/hydrogen. For analytics, import the Analytics object from @shopify/hydrogen and render Analytics.Provider and the other Analytics.* components. Use @shopify/hydrogen-react only for an export that @shopify/hydrogen doesn’t have. When both packages export a component with the same name, such as RichText or ShopPayButton, import the component from @shopify/hydrogen.
• Cart: Manage the cart with CartForm. Don’t use the CartProvider, useCart, or cart button components from @shopify/hydrogen-react.
• Server imports: Keep the existing server imports when you edit a project. In 2025.7.1 and later, import createRequestHandler from @shopify/hydrogen. In 2025.7.0, import createRequestHandler from @shopify/hydrogen/oxygen. In 2025-07 and later, import sessions and cookies from react-router, and type loaders with the Route types that React Router generates in ./+types/. Projects on 2025-05 and earlier import sessions and server types from @shopify/remix-oxygen, and import createRequestHandler from @shopify/remix-oxygen or @shopify/hydrogen. Some projects on 2025-07 through 2026-04 still import from @shopify/remix-oxygen 3.x, which is deprecated. Each 3.x release requires one React Router version, such as 7.6.0 for 3.0.0. Keep react-router at the version that the installed release requires.
• Routing imports: In 2025-05 and later, import routing and data APIs from react-router. In 2025-04 and earlier, import routing and data APIs from Remix packages such as @remix-run/react.
• Not available: Hydrogen 2026-04 and earlier doesn’t export createShopifyRequestContext, handleShopifyRoutes, or formatMoney.
• Docs: The docs for Hydrogen 2026-04 and earlier cover versions 2025-07 through 2026-04. Pass the chosen version to the docs search. For 2025-05 and earlier, pass 2025-07, and change the imports in the examples to match the server imports and routing imports for the project’s version. Use the Hydrogen 2026-04 reference (opens in a new tab), the Hydrogen React 2026-04 reference (opens in a new tab), and the Legacy Hydrogen guides (opens in a new tab). In a reference URL, replace 2026-04 with the version that you passed to the search.
• Recipes: Use a recipe from the Hydrogen Cookbook (opens in a new tab) when one fits the request. The recipes use React Router. For 2025-04 and earlier, import Remix components and hooks such as Link and useLoaderData, and route types such as MetaFunction, from @remix-run/react. Import server helpers such as redirect and LoaderFunctionArgs from @shopify/remix-oxygen.
• New storefronts: To create, run, and deploy a storefront on Oxygen, follow Getting started with Hydrogen and Oxygen (opens in a new tab).
• mock.shop: Without a store, follow How to use mock.shop (opens in a new tab).