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. Use the repository’s committed lockfile and runtime requirements when installing dependencies.

1. Create your copy

Setup

Code in bash

Start from the reference storefront repository. Use your own repository when you are ready to maintain a customized storefront.

2. Configure the environment

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

Code in bash

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 before changing the UI.

5. Customize by feature

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 and account guide when changing those flows.