How to Build a Custom Ecommerce Store with Thor Commerce and AI

Rasmus — Sun, 13 Sep 2026 21:27:58 +0000

Building a custom ecommerce storefront used to mean choosing between two uncomfortable options: start from a rigid template, or spend months rebuilding catalog, pricing, inventory, cart, checkout, and customer logic from scratch.

Headless commerce changes that tradeoff. You keep a purpose-built commerce backend, but your storefront remains ordinary application code that you can shape around your brand and buying journey.

In this tutorial, you will create a working custom storefront with Thor Commerce, its open-source Next.js storefront, and an AI coding agent such as Claude Code, Codex, or Cursor. You do not need to ask the agent to invent checkout logic. Instead, it works inside a typed, documented foundation that already covers product discovery, market-aware pricing, carts, checkout, payments, orders, and customer accounts.

By the end, you will have:

A local Next.js storefront connected to your Thor project
Products and prices resolved for the correct market
A persistent cart and checkout flow
A safe workflow for customizing the storefront with an AI coding agent
A clear path to production deployment

What is Thor Commerce?

Thor Commerce is a headless commerce platform for B2B, DTC, and hybrid businesses. Thor manages the commerce engine—catalog, contextual pricing, inventory, customers, carts, checkout, and orders—while you control the customer experience.

The separation is straightforward:

The Admin API is the control plane for trusted, server-side operations such as managing products, prices, inventory, stores, channels, customers, discounts, and orders.
The Storefront API powers buyer-facing product discovery, cart, checkout, and customer account flows.
Your storefront decides how those capabilities look and feel across web, mobile, portals, and other channels.

Both APIs are GraphQL. Your application selects only the data it needs, and generated TypeScript types keep the storefront aligned with the schema.

Thor also resolves commerce in context. The same product can have different availability and pricing depending on the store, country, currency, price channel, customer identity, or customer group. That is especially useful when a business sells DTC and B2B from one catalog.

Thor Admin brings product status, variants, inventory, and publications into one catalog view.

Why Thor Commerce works well with AI coding agents

AI coding agents are most useful when they have strong boundaries and a reliable source of truth. Ecommerce is too important for an agent to guess how totals, stock, payments, or permissions work.

Thor gives the agent four useful guardrails:

Typed GraphQL contracts. Operation names, inputs, nullability, and error types can be checked against the Admin or Storefront schema.
Task-oriented documentation. The Thor developer guides describe prerequisites, ordered steps, expected outcomes, and recovery behavior.
Agent-ready sources. Thor publishes an llms.txt index and Markdown versions of its docs. The starter also includes AGENTS.md plus Thor API skills that coding agents can read before changing commerce operations.
A working reference implementation. The starter already demonstrates the correct boundaries for credentials, request context, cart persistence, GraphQL documents, and generated types.

The result is a better division of labor: you describe the experience and business outcome; the agent reads the relevant contract, changes the code, and proves the result with lint, build, and browser checks.

What you will build

We will start from Thor's reference storefront rather than an empty folder. It uses:

Next.js 16 and React 19
TypeScript and typed GraphQL documents
React Server Components and Server Actions
Country-prefixed, multi-market routing
Product listings, product details, variants, categories, collections, sorting, and filters
Cookie-backed carts
Custom and hosted checkout options
Stripe and manual payment flows
Customer registration, login, sessions, and account pages
OpenNext configuration for Cloudflare Workers

This is a reference implementation, not a locked theme. The commerce plumbing is present, but the components, CSS, routes, queries, and buying journey remain yours to change.

A product can expose multiple active variants while Thor keeps SKU and status explicit.

Prerequisites

You need:

Node.js 20.9 or newer
pnpm
Git
A Thor Commerce project with Storefront API access
A configured store and at least one published, priced variant
An AI coding agent that can read and edit a local repository

If your Thor project is empty, follow the guides to configure a store and create and publish a product first. Product content, variants, price, inventory, activation, and publication are separate pieces of sellability, so verify the full sequence before debugging the storefront.

Use a development project and test payment method while building. Keep all credential values in environment files or your hosting provider's secret store—never paste production secrets into an AI prompt.

Step 1: Create your storefront

Create a repository from the GitHub template, or clone the public reference directly:

git clone https://github.com/thor-commerce/next-thor-storefront.git
cd next-thor-storefront
pnpm install

Before prompting your coding agent, ask it to read AGENTS.md. That file directs it to the included Thor Admin and Storefront API skills, which explain how to discover and validate the GraphQL schema.

A useful first prompt is:

Read AGENTS.md and the relevant Thor Commerce Storefront API skill before making changes.
Then map the repository for me: explain where product queries, product pages, cart actions,
checkout, customer authentication, market configuration, and generated GraphQL types live.
Do not change any files yet.

This gives you a quick architectural tour and makes the agent establish the right context before it writes code.

Step 2: Connect the storefront to Thor Commerce

Copy the example environment file:

cp .env.example .env

Add your project values:

THOR_PROJECT="your-project-slug"
THOR_STOREFRONT_API_KEY="your-storefront-token"
BETTER_AUTH_SECRET="generate-a-new-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="generate-a-new-persistent-key"

Use the project slug from your Thor project URL. A store ID is a resource inside that project; it is not the project slug.

The storefront token is sent server-side as X-Thor-Storefront-Token. Do not use an Admin API key here, do not expose a private value with a NEXT_PUBLIC_ prefix, and do not commit .env.

Next, edit src/lib/thorcommerce/config.ts and replace the example market configuration with your real:

Country codes
Default country
Thor store IDs
Currencies
Store and market mappings

Keep this context consistent throughout catalog, cart, and checkout requests. A product can exist in Admin and still be absent from a storefront when its publication, store, channel, price, currency, country, or inventory context does not match.

If you want the agent to help, be explicit about the boundary:

Configure this storefront for Denmark and Germany using the store IDs and currencies already
present in my local environment configuration. Read the Thor Next.js storefront guide first.
Keep secrets server-side, do not invent missing IDs, and show me the exact files you plan to edit.

Step 3: Generate the typed GraphQL client and run the app

Generate TypeScript types from the GraphQL documents:

pnpm codegen

Then start the development server:

pnpm dev

Open http://localhost:3000. The middleware should redirect to a country-prefixed route such as /dk.

You should see products from the store configured for that market. Open a product, select a variant, and add it to the cart. Refresh the page and confirm the cart persists.

If the catalog is empty, do not replace IDs until something appears. Ask the agent to trace the request context and check each layer:

The Thor storefront returns no products for /dk. Diagnose this without changing data first.
Verify the project slug, Storefront token, store ID, country, currency, price channel,
product and variant status, publication window, price, and purchase availability.
Show the evidence for the first failing layer.

That prompt is intentionally diagnostic. It prevents a coding agent from hiding a configuration problem behind a UI workaround.

Step 4: Customize the design

The storefront groups code by commerce domain, so you can change one experience without searching the entire repository:

What you want to change	Start here
Product queries	`src/lib/thorcommerce/storefront/queries/products.graphql`
Product listing and detail UI	`src/features/products`
Cart state and actions	`src/features/cart`
Checkout steps	`src/features/checkout`
Customer accounts	`src/features/account` and `src/lib/auth.ts`
Market routing	`src/lib/thorcommerce/config.ts`, `src/lib/request-context.ts`, and `src/middleware.ts`
Shared UI	`src/components`

You can now give the coding agent a visual and behavioral brief. For example:

Redesign the product listing and product detail pages for a minimal Scandinavian homeware brand.
Keep the existing Thor Commerce data flow, variant selection, market-aware prices, availability,
and add-to-cart behavior intact. Use the existing CSS Modules and accessible components.
Do not add mock commerce data. Verify the result at mobile and desktop widths.

The important phrase is “keep the existing data flow intact.” A redesign should not move credentials into the browser or replace calculated backend values with frontend guesses.

Step 5: Add a custom commerce feature

Suppose you want to display a structured material specification on product pages and make it available to filters or integrations. Thor supports typed metafields for named, validated custom data.

Ask the agent to start with the contract rather than a guessed field:

I want products to have a public, typed material specification that appears on the product page.
Read Thor's metafields documentation and inspect the Admin and Storefront schemas.
Propose the metafield definition, explain how its value is assigned through the product update input,
add the Storefront GraphQL selection, regenerate types, and render it accessibly.
Use only a development project. Stop if the required owner type or field is not in the schema.

Why this works:

The agent has a specific outcome.
It knows which API controls configuration and which API serves buyers.
It must verify the live contract before writing an operation.
It updates the source .graphql document and runs pnpm codegen instead of editing generated files.
It has a concrete UI verification target.

After any GraphQL selection changes, rerun:

pnpm codegen
pnpm lint
pnpm build

Step 6: Test cart and checkout as commerce flows

Cart and checkout deserve more than a visual spot-check. Thor calculates prices, discounts, stock, shipping eligibility, tax, and totals against the current commerce context.

Your storefront should render the returned cart state, not independently calculate what the customer owes. After a cart mutation, use the latest returned or refetched cart because several values can change together.

Give your coding agent an outcome-based test brief:

Verify one complete test purchase in this storefront. Use an existing sellable variant and the
configured test payment method. Confirm variant selection, add to cart, quantity update,
cart persistence after refresh, shipping method selection, payment, order completion,
and the resulting order in Thor Admin. Report evidence for each step and any untested dependency.
Do not use production credentials or a live payment method.

Also test failure paths: out-of-stock variants, stale carts, rejected discount codes, unavailable shipping methods, payment cancellation, and expired customer sessions. A storefront is production-ready only when recovery paths are understandable to buyers.

Step 7: Deploy

Before deployment, run:

pnpm lint
pnpm build

The starter includes OpenNext and Wrangler configuration for Cloudflare Workers, including R2-backed incremental caching. Review the resource names, bindings, secrets, country detection, and build scripts before deploying. A cloned configuration does not provision production infrastructure automatically.

If you deploy to another Next.js-compatible platform, adapt platform-specific country detection in src/middleware.ts. The CF-IPCountry header is specific to Cloudflare.

Whichever platform you choose, verify:

Production environment variables are stored as secrets
Store and market IDs point to the intended Thor project
Payment, tax, and shipping configuration use the correct environment
Authentication callbacks use the production origin
Cart, sign-in, market switching, and a test order work after deployment
Logging and monitoring do not expose tokens or customer data

A repeatable workflow for AI-assisted commerce development

The best prompts follow a simple loop:

State the outcome. Describe the buyer or operator behavior you want.
Name the surface. Say whether it belongs in the Storefront, an Admin integration, or an embedded app.
Point to authoritative context. Ask the agent to read AGENTS.md, the focused Thor guide, and the relevant GraphQL schema.
Set boundaries. Identify the development environment and forbid invented IDs, schema fields, secrets, and mock data.
Require verification. Ask for changed files, commands run, observed behavior, and untested dependencies.

This is more reliable than asking an agent to “build an ecommerce site” in one enormous prompt. The agent handles bounded implementation tasks while Thor remains the source of truth for commerce behavior.

What can you build with Thor Commerce?

Because storefront presentation is decoupled from the commerce core, the same foundation can support:

DTC storefronts with custom brand experiences
B2B portals with customer-group pricing and account-specific buying flows
Hybrid B2B and DTC commerce using one catalog
Multi-market and multi-currency storefronts
Product discovery with categories, collections, search, sorting, and facets
Custom checkout, hosted checkout, or a mix of both
Customer account areas and order history
ERP, PIM, fulfillment, email, and payment integrations through APIs and webhooks
Embedded operational apps inside the Thor dashboard

You can begin with the reference storefront, then replace the visual system and extend one feature at a time without rebuilding the underlying commerce engine.

Frequently asked questions

Is Thor Commerce headless?

Yes. Thor provides Admin and Storefront GraphQL APIs while your frontend remains a separate application. You control the framework, design system, routes, content, and interaction model.

Can I use Claude Code with Thor Commerce?

Yes. You can use Claude Code or another repository-aware coding agent. The Thor storefront includes AGENTS.md and portable API skills, and the documentation provides agent-friendly Markdown sources. The same safety rule applies to every agent: keep credentials in the application's secret environment, not in prompts.

Does the starter support B2B ecommerce?

It provides the foundation for B2B, DTC, and hybrid experiences, including contextual pricing, customer-aware flows, markets, carts, checkout, and accounts. Your final B2B experience may add business-specific approval, purchasing, or account UI on top of those primitives.

Can I build a custom checkout?

Yes. The starter includes checkout UI for customer details, shipping, gateway selection, Stripe payments, manual payments, and order completion. Thor can also provide a hosted checkout URL when that is a better fit.

Can I deploy somewhere other than Cloudflare?

Yes. The storefront uses standard Next.js patterns. Cloudflare configuration is included, but you can adapt the project for another compatible platform.

Is the starter production-ready?

It is a working reference implementation and a strong starting point. Before launch, review your market, payment, tax, shipping, authentication, security, observability, performance, and accessibility requirements.

Start building

Thor Commerce gives your coding agent something valuable: a real commerce model, typed API contracts, focused documentation, and a working storefront to extend.

Start with the Thor Commerce Next.js storefront, connect it to a development project, and make one verified improvement at a time.

DEV Community: Rasmus