# Build with the Next.js storefront

Use the Thor Next.js storefront as a starting point for product discovery, cart, checkout, and customer accounts.
It keeps Storefront requests on the server and organizes GraphQL documents separately from the interface.
The included market and deployment values are examples that must be adapted to your project.

## Before you begin

You need Node.js compatible with the repository's Next.js version, pnpm, and a Thor project with Storefront access.
Prepare a store and at least one sellable variant using [Create and publish a product](/guides/catalog/create-product).
Use the repository's committed lockfile and runtime requirements when installing dependencies.

## 1. Create your copy


Setup

```bash
git clone https://github.com/thor-commerce/next-thor-storefront.git
cd next-thor-storefront
pnpm install
cp .env.example .env

```


Start from the [reference storefront repository](https://github.com/thor-commerce/next-thor-storefront).
Use your own repository when you are ready to maintain a customized storefront.

## 2. Configure the environment

| Variable | Set it to |
| --- | --- |
| `THOR_PROJECT` | Your project slug used in the Storefront URL |
| `THOR_STOREFRONT_API_KEY` | Your Storefront token, not an Admin API key |
| `BETTER_AUTH_SECRET` | A newly generated application secret |
| `BETTER_AUTH_URL` | Your application's origin, locally `http://localhost:3000` |
| `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` | A suitable persistent key for the deployment described by the template |

Use the commands and comments in `.env.example` to generate new keys.
Generate independent secrets and store production values in your hosting platform's secret configuration.
Do not prefix private values with `NEXT_PUBLIC_`.
The variable called `THOR_STOREFRONT_API_KEY` is sent as `X-Thor-Storefront-Token` by the transport helper.

## 3. Replace the example market configuration

Edit `src/lib/thorcommerce/config.ts` to use your real store IDs and supported currencies and countries.
Remove example markets you do not support.
The example's country labels do not prove that your project has matching local-currency prices.

Inspect `src/middleware.ts` and `src/lib/request-context.ts` together.
They resolve the country-prefixed route and the store/currency context used by requests.
If you need country-specific prices, additional price channels, or translated content, pass those dimensions consistently through catalog and cart operations.
Do not assume every available context dimension is already wired into every example query.

## 4. Generate types and start


Run locally

```bash
pnpm codegen
pnpm dev

```


Open the local URL printed by the server.
Expect a country-prefixed storefront route and products from your configured store.
If the catalog is empty, verify the Storefront request and [publication context](/concepts/catalog/publication) before changing the UI.

## 5. Customize by feature

| Change | Start in |
| --- | --- |
| Product queries | `src/lib/thorcommerce/storefront/queries/products.graphql` |
| Product pages | `src/features/products` |
| Cart state and actions | `src/features/cart` |
| Checkout steps | `src/features/checkout` |
| Customer sessions | `src/lib/auth.ts` and `src/features/account` |
| Transport and customer headers | `src/lib/thorcommerce/storefront/index.ts` |
| Responsive images | `src/components/thor-image/thor-image.tsx` |

Edit source GraphQL documents and run `pnpm codegen` after changing selections.
Do not edit `generated/types.generated.ts` by hand.
Check typed mutation errors in the action that calls each mutation before reporting success.
An example helper is a starting point, not a reason to omit error handling in your application.

## Verify before deployment

Run `pnpm lint` and `pnpm build` in your storefront copy.
Test product selection, a persisted cart after refresh, customer sign-in and sign-out, a market change, and a test order.

The repository includes OpenNext and Cloudflare configuration.
Review its resource names, bindings, secrets, country detection, and build scripts before using it for your own deployment.
A cloned configuration does not provision your production resources.
Use the [cart guide](/guides/storefront/cart-and-checkout) and [account guide](/guides/storefront/customer-accounts) when changing those flows.