# Build a Hydrogen storefront with mock.shop

Use Shopify Hydrogen to build a custom Shopify storefront with mock.shop's
products, collections, and carts. You can start locally without a Shopify
account, store, or API token, then connect the app to a real store later.

## Choose a catalog

[Search the directory](shop-directory.md) for the products your task needs.
Compare the matches and read the selected store's `/llms.txt`. Keep its
`storefrontApiUrl`: the app should query that catalog. The default store is
an apparel sample; use it when apparel fits your task.

## Start the Hydrogen app

Use Node.js 22 or 24. The [mock.shop starter](https://github.com/Shopify/mock-shop-starter)
already includes Hydrogen routes, Storefront API queries, and a cart:

```sh
git clone https://github.com/Shopify/mock-shop-starter.git my-store
cd my-store
cp .env.example .env
```

Set `PUBLIC_STORE_DOMAIN` in `.env` to the hostname from the selected
`storefrontApiUrl`, without `https://` or `/api`. For example, if you selected
`https://furniture.mock.shop/api` for a furniture task:

```dotenv
PUBLIC_STORE_DOMAIN=furniture.mock.shop
```

Leave `PUBLIC_STOREFRONT_API_TOKEN` and `PRIVATE_STOREFRONT_API_TOKEN` unset for
`*.mock.shop`. When using mock-shop's development or staging hosts instead,
set `PUBLIC_STOREFRONT_API_TOKEN=public` to satisfy Hydrogen's SDK validation;
this literal value is not a credential. Keep the private token unset.
Keep the starter's local `SESSION_SECRET`.

## Customize the storefront

The starter's source is available immediately after cloning. Configure the
catalog and customize its existing routes before installing dependencies.

Keep `createHydrogenContext` from `@shopify/hydrogen` in `app/lib/context.ts`
and the routes that use its Storefront API and cart clients. Adapt the layout,
styling, product pages, and collections to the brief while continuing to query
the selected catalog. Installing `@shopify/hydrogen-react` components into a
generic React app alone does not create a full Hydrogen storefront.

If the task explicitly calls for an existing framework, mock.shop's Storefront
API can also be used there. For a new Hydrogen app, the starter supplies the
commerce integration so you do not need to replace it with local product
arrays or a separate cart implementation.

## Install dependencies and run

After configuring and customizing the starter, install dependencies and start it:

```sh
npm install
npm run dev
```

Open the localhost URL printed by the dev server. Restart it after changing
the catalog in `.env`.

## Use real commerce or install a published theme

mock.shop checkout is simulated and creates no real orders or payments. When
ready for real commerce, follow [Hydrogen's store connection and deployment
steps](https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started)
to link a Shopify store, pull its environment variables, and deploy to Oxygen.

Installing a mock store's exact published Liquid theme on a merchant's Online
Store is a separate workflow. For that task, follow "Reproduce this shop's
look" in the selected store's `/llms.txt`, including its artifact and catalog
copying instructions. Those instructions are not prerequisites for building a
new Hydrogen storefront with the same mock catalog.