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

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 includesAGENTS.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