Deploy a template

This tutorial gets a Hydrogen storefront running from a starter template. You create the storefront from your Shopify store, deploy it to a host, and then set up a local copy to work on.

Anchor to What you'll learnWhat you'll learn

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

• Create a storefront from a starter template, and deploy it to Oxygen or Vercel.
• View your deployed storefront, and share it with others.
• Set up a local copy of your storefront that reads from your store.
• Find the parts of the template that fetch data, handle requests, and manage the cart.

Anchor to RequirementsRequirements

• A Shopify store that you can connect a storefront to, and a staff account with permission to manage apps and sales channels.
• Install Node.js. The React Router template needs version 22 or 24, and Vercel Shop needs version 24.
• For the React Router template, a GitHub account. Shopify creates the repository for your storefront in it.
• For Vercel Shop, a Vercel account, a GitHub, GitLab, or Bitbucket account, and pnpm version 12.

Anchor to Step 1: Create and deploy your storefrontStep 1: Create and deploy your storefront

You can start from one of two templates that are built on Hydrogen. Shopify maintains the React Router template, and Vercel maintains Vercel Shop. Each one comes with a home page, collection pages, product pages, search, and a cart already built. The React Router template also includes customer accounts, analytics, and a consent banner. Vercel Shop includes customer accounts and Shopify analytics too, but you need to enable them to use them.

Pick the template that matches your framework, and follow its steps:

Anchor to Step 2: Set up your local copyStep 2: Set up your local copy

To work on the code, clone the repository that you created in Step 1, and install dependencies:

git clone <your-repository-url> my-store
cd my-store
npm install

git clone <your-repository-url> my-store
cd my-store
pnpm install

Your hosted storefront already has your store's credentials, but your local copy doesn't. Add them as described for your template.

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

Anchor to React Router on OxygenReact Router on Oxygen

Oxygen keeps your storefront's environment variables in the Shopify admin. To copy them to your local copy, run the following commands from your project's directory. link connects the directory to a storefront in the Shopify admin, so select the storefront that you created in Step 1. env pull copies the storefront's environment variables into .env:

To use an existing private Storefront API token without linking, add your store domain and token to .env instead:

PUBLIC_STOREFRONT_ID is optional. Shopify analytics turn on when it's set. The template gets your shop ID from the Storefront API, so you don't set it for analytics.

Until it finds a private Storefront API token, the React Router template reads demo data from mock.shop instead of your store.

Anchor to Vercel ShopVercel Shop

Copy .env.example to .env.local, and set the same store domain, public access token, and shop ID that you entered in Vercel:

The first three variables are required. NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID is optional, and attributes storefront traffic and analytics to your Headless storefront. Find it in the storefront's URL in the Headless channel. It's the number after /headless/. For other settings, refer to Vercel Shop's environment variables.

When you change a variable later, also change it in your Vercel project's Settings > Environment Variables, and then redeploy.

Anchor to Customer accountsCustomer accounts

Both templates include customer accounts, but they need extra environment variables and HTTPS (a public tunnel for local Vercel Shop sign-in). On Oxygen, your storefront provides the variables. To learn about setting them up, refer to Set up customer accounts. In Vercel Shop, customer accounts are off by default. To turn them on, refer to Vercel Shop's authentication guide.

Anchor to Step 3: Run your storefrontStep 3: Run your storefront

Start the development server:

npm run dev

pnpm dev

Open the local URL that the command prints. The React Router template runs at http://localhost:5173, and Vercel Shop runs at http://localhost:3000.

Your local storefront shows your store's products, like your deployed one. Browse a collection, open a product, choose a variant, and add it to your cart. The cart drawer opens with your item.

Anchor to Step 4: Explore your storefrontStep 4: Explore your storefront

Each template is an ordinary app for its framework. Hydrogen adds three things to it:

• Request handlers that run before your router, and serve the routes that every Shopify storefront needs, like /api/cart and cart permalinks.
• A Storefront API client that your pages use to fetch products, collections, and other store data.
• Cart state that every component that shows the cart shares, and that stays in sync with Shopify.

The following table shows where to find each part in each template:

In the React Router template, open the home page's file, app/routes/home.tsx, and find the Home query that fetches the products and collections that the page shows. To show more data on the page, add fields to that query. In Vercel Shop, find the queries for each page in lib/shopify/operations/. To learn how queries work, refer to Query the Storefront API.

Anchor to Next stepsNext steps

Query the Storefront API

Learn how the template's Storefront API client fetches and caches data.

Deploy your storefront

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