Add Hydrogen to an existing project

You don't need a starter template to use Hydrogen. You can add it to a new or existing project that uses any framework that runs server code. This guide shows you how to install Hydrogen, connect it to a store, wire it into your app's request lifecycle, and show your store's products on a page.

If you want a storefront that's already built, then start from a starter template instead. Refer to Deploy a template.

Anchor to What you'll learnWhat you'll learn

In this guide, you'll learn how to do the following tasks:

• Install Hydrogen in a project that uses the framework of your choice.
• Configure environment variables for mock.shop or for your own store.
• Wire the Storefront API client, request handlers, and customer accounts into your app.
• Show your store's products on a page, with a link to buy each one.
• Check that your storefront works.

Anchor to RequirementsRequirements

• Install Node.js version 22 or 24.
• Use a JavaScript project with a package.json file at its root, built with a framework that runs server code, like route handlers, middleware, loaders, or server functions. Hydrogen runs before your router on each request, so apps that are browser-only or configured only for static output don't work.
• To connect your own store, get Storefront API access through the Headless channel or the Hydrogen channel. You don't need a store to start building with mock.shop.

Anchor to Step 1: Install HydrogenStep 1: Install Hydrogen

Create a project with your framework's CLI, like npx create-next-app@latest or npx create-react-router@latest, or use a project you already have. Then run the Hydrogen setup command from the project's root directory:

The setup command does the following tasks:

• Installs @shopify/hydrogen with your project's package manager, which it detects from your lockfile. If @shopify/hydrogen is already in your package.json file but isn't installed, then it runs your package manager's install command instead.
• Adds agent instructions that match the installed Hydrogen version to your project's .claude and .agents directories.

The setup command doesn't change your app's code. You wire Hydrogen into your app in Step 3 and Step 4. You can follow those steps yourself, or open the project in your coding agent and ask it to follow them for you:

The agent works through the same steps in the same order, and checks each one before it starts the next.

Anchor to Step 2: Configure environment variablesStep 2: Configure environment variables

Hydrogen reads its store connection from environment variables. Until you add a private Storefront API token, you can build against mock.shop, a public Storefront API with demo data that doesn't need a token.

Use the variable names in this step throughout your app. In Next.js, replace PUBLIC_ with NEXT_PUBLIC_, and use NEXT_PUBLIC_SHOP_ID.

Anchor to Use mock.shopUse mock.shop

mock.shop is a catalog of demo stores, each on its own host. The store at mock.shop sells apparel. For other catalogs, refer to the directory at mock.shop/llms.txt. To build against the demo catalog that's closest to your store, set your store domain to its host and leave the tokens out:

Keep the public Storefront API token commented out until you have one. An empty assignment, like PUBLIC_STOREFRONT_API_TOKEN=, loads as an empty string, and the Storefront API client rejects empty tokens. A missing token means tokenless access.

Connect a real store to test real checkout and customer accounts.

Anchor to Use your own storeUse your own store

Get your store domain and tokens from the Headless or Hydrogen channel in the Shopify admin, then add them to your project's .env file.

The private Storefront API token is server-only. Never expose it to the browser, and never give it a browser prefix like NEXT_PUBLIC_.

If you deploy to Oxygen and your storefront is linked to the Hydrogen channel, then you can pull these values with Shopify CLI instead of copying them by hand:

The following table describes each variable:

To generate a session secret, run the following command:

Anchor to Step 3: Wire Hydrogen into your appStep 3: Wire Hydrogen into your app

This step connects Hydrogen to your app's request lifecycle. Complete each part in order, and check it before you start the next. After each part that changes code, run your app's typecheck script and fix any errors. Type errors compound, so they're easier to fix one part at a time.

Anchor to Keep environment access on the serverKeep environment access on the server

Read environment variables only in server code. Never read process.env, import.meta.env, or your framework's environment modules from client components or from modules that client components import.

Resolve values that come from environment variables on the server, and pass them to client components as props or loader data. For example, build the shop object that ShopifyScripts needs on the server. Browser code calls Shopify through Hydrogen's same-origin routes, so private tokens never leave the server.

For which files run on the server in React Router and Next.js, refer to Framework wiring.

Before you continue, confirm that no client component, and no module that a client component imports, reads environment variables.

Anchor to Set up route templatesSet up route templates

Hydrogen builds links to products, collections, and other Shopify resources from a shared route manifest. If your app already has routes for these resources, then keep them. Otherwise, use the standard paths:

Use the plural /products, not /product. Some paths, like /api/cart, /checkout, and /cart/{variantId}:{quantity}, belong to Hydrogen's request handlers, so don't create pages for them.

To create the manifest, follow Configure route templates.

Before you continue, confirm that your route templates module exports your manifest. You check that Shopify's standard URLs reach your pages after you wire request handlers.

Anchor to Create the Storefront API clientCreate the Storefront API client

Create the Storefront API client for your framework by following Query the Storefront API. Then add hydrogen gql check to your existing typecheck script, so that the script validates your queries against the Storefront API schema. Run it after TypeScript and any route type generation:

{
  "scripts": {
    "typecheck": "react-router typegen && tsc && hydrogen gql check --fail-on-warn"
  }
}

{
  "scripts": {
    "typecheck": "next typegen && tsc --noEmit && hydrogen gql check --fail-on-warn"
  }
}

If you use mock.shop, then create a public client without a token, because mock.shop rejects private tokens. Refer to Use mock.shop during development.

For more information about query validation, refer to Type and validate Storefront API queries.

Before you continue, confirm that typecheck passes. You run your first query in Step 4.

Anchor to Wire request handlersWire request handlers

Run Hydrogen's request handlers before your router, and check for Shopify redirects after your router returns a 404. Follow Wire Hydrogen request handlers.

Then make the Storefront API client available to your pages:

import type {StorefrontClient} from '@shopify/hydrogen';
import {createContext} from 'react-router';

export const storefrontContext = createContext<StorefrontClient>();

import type {Route} from './+types/root';
import {storefrontContext} from './lib/context';
import {handleRequest} from './lib/shopify';

export const middleware: Route.MiddlewareFunction[] = [
  ({request, context}, next) =>
    handleRequest(request, async (_request, storefrontClient) => {
      context.set(storefrontContext, storefrontClient);
      return next();
    }),
];

import type {StorefrontClient} from '@shopify/hydrogen';
import {createContext} from 'react-router';

export const storefrontContext = createContext<StorefrontClient>();

import type {Route} from './+types/root';
import {storefrontContext} from './lib/context';
import {handleRequest} from './lib/shopify';

export const middleware: Route.MiddlewareFunction[] = [
  ({request, context}, next) =>
    handleRequest(request, async (_request, storefrontClient) => {
      context.set(storefrontContext, storefrontClient);
      return next();
    }),
];

For the full wiring in each framework, refer to Framework wiring.

Before you continue, confirm that typecheck passes. You check the request handlers in Step 4.

Anchor to Set up customer accountsSet up customer accounts

Customer accounts need a real store. If you're using mock.shop, then skip this part until you connect your store.

Create the customer session, and register the account handlers with your request handlers. Follow Steps 1 to 3 of Set up customer accounts.

Before you continue, confirm that typecheck passes.

Anchor to Step 4: Show products on a pageStep 4: Show products on a page

Add a page that queries the first few products in your store and lists them. Each product shows its title, its price, and a Buy now link. The page is the first place your app runs a Storefront API query, so it shows that your client, your request handlers, and your store connection work together.

Keep the following in mind:

• formatMoney() formats the amount and currency that Shopify returns. Pass your customer's locale instead of en-US when your storefront supports more than one.
• The Buy now link uses Shopify's cart permalink format, /cart/{variantId}:{quantity}, with the number at the end of the variant ID. Hydrogen's request handlers answer it and redirect the customer to your store's checkout with that product in the cart, so you don't need a page for it.

Anchor to Check the pageCheck the page

Start your framework's development server, like npm run dev, and open the local URL that it prints. Then confirm the following:

• Your home page lists products from your store or from mock.shop, each with a price.
• typecheck passes, and your editor shows the query result's fields as typed.
• /graphiql returns a 200 response.
• If you connected your own store, then Buy now opens your store's checkout, and /admin redirects to the Shopify admin. Buy now and /admin don't work with mock.shop.
• If you set up HTTPS and customer accounts, then /account/login redirects to Shopify's OAuth /oauth/authorize endpoint.

Customer accounts need HTTPS. To test sign-in locally, refer to Test sign-in locally with HTTPS.

Anchor to Step 5: Check your storefrontStep 5: Check your storefront

Run your app's own checks. Look in your package.json file for the following scripts, and run the ones that exist, in this order:

1. format, to fix formatting.
2. lint, typecheck, or check. Confirm that typecheck still runs hydrogen gql check before you trust a passing result.
3. build.
4. test. If your project uses Playwright, then run it headless.
5. format:check, if it's separate from format.

Run the checks again after every code change. A check that passed before your last change doesn't count.

Then test your storefront while it runs. Work through the production checklist against your development server, and against a production build if your framework can run one locally.

Anchor to Next stepsNext steps

Build the rest of your storefront's features in the following order. Later features build on earlier ones. For example, the cart drawer reuses your cart page's line items, and analytics events depend on Shopify's runtime scripts.

Build your storefront's UI with the styling approach that your app already uses, like Tailwind CSS or CSS Modules.

Your app also owns image optimization and SEO. Use your framework's image component, or <img srcset> with Shopify CDN URLs that set sizing parameters from ImageTransformInput. Render meta tags, Open Graph tags, and structured data with your framework's metadata API and Storefront API data.

After you add each feature, run the checks in Step 5 again. When your storefront is ready, deploy it:

Deploy your storefront

Deploy your storefront to Oxygen, Vercel, or another runtime.

Production checklist

Check your storefront's routes, cart, and analytics before you launch.

Hydrogen API reference

Explore the functions, stores, and components that Hydrogen exports.