{"slug": "how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai", "title": "How to Build a Custom Ecommerce Store with Thor Commerce and AI", "summary": "A developer tutorial demonstrates building a custom headless ecommerce storefront using Thor Commerce, its open-source Next.js reference implementation, and AI coding agents such as Claude Code, Codex, or Cursor. The approach pairs Thor's GraphQL commerce backend—covering catalog, contextual pricing, inventory, carts, checkout, and orders—with generated TypeScript types and agent-readable files like AGENTS.md and llms.txt to keep AI-generated code grounded in a documented contract.", "body_md": "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.\n\nHeadless 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.\n\nIn this tutorial, you will create a working custom storefront with [Thor Commerce](https://thorcommerce.io/), its open-source [Next.js storefront](https://github.com/thor-commerce/next-thor-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.\n\nBy the end, you will have:\n\n[Thor Commerce](https://thorcommerce.io/) 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.\n\nThe separation is straightforward:\n\nBoth APIs are GraphQL. Your application selects only the data it needs, and generated TypeScript types keep the storefront aligned with the schema.\n\nThor 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.\n\n*Thor Admin brings product status, variants, inventory, and publications into one catalog view.*\n\nAI 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.\n\nThor gives the agent four useful guardrails:\n\n`llms.txt`` AGENTS.md` plus Thor API skills that coding agents can read before changing commerce operations.\nThe 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.\n\nWe will start from Thor's reference storefront rather than an empty folder. It uses:\n\nThis 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.\n\n*A product can expose multiple active variants while Thor keeps SKU and status explicit.*\n\nYou need:\n\nIf your Thor project is empty, follow the guides to [configure a store](https://docs.thorcommerce.io/guides/catalog/configure-store) and [create and publish a product](https://docs.thorcommerce.io/guides/catalog/create-product) first. Product content, variants, price, inventory, activation, and publication are separate pieces of sellability, so verify the full sequence before debugging the storefront.\n\nUse 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.\n\nCreate a repository from the [GitHub template](https://github.com/new?template_name=next-thor-storefront&template_owner=thor-commerce), or clone the public reference directly:\n\n```\ngit clone https://github.com/thor-commerce/next-thor-storefront.git\ncd next-thor-storefront\npnpm install\n```\n\nBefore 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.\n\nA useful first prompt is:\n\n```\nRead AGENTS.md and the relevant Thor Commerce Storefront API skill before making changes.\nThen map the repository for me: explain where product queries, product pages, cart actions,\ncheckout, customer authentication, market configuration, and generated GraphQL types live.\nDo not change any files yet.\n```\n\nThis gives you a quick architectural tour and makes the agent establish the right context before it writes code.\n\nCopy the example environment file:\n\n```\ncp .env.example .env\n```\n\nAdd your project values:\n\n```\nTHOR_PROJECT=\"your-project-slug\"\nTHOR_STOREFRONT_API_KEY=\"your-storefront-token\"\nBETTER_AUTH_SECRET=\"generate-a-new-secret\"\nBETTER_AUTH_URL=\"http://localhost:3000\"\nNEXT_SERVER_ACTIONS_ENCRYPTION_KEY=\"generate-a-new-persistent-key\"\n```\n\nUse the project slug from your Thor project URL. A store ID is a resource inside that project; it is not the project slug.\n\nThe 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`.\n\nNext, edit `src/lib/thorcommerce/config.ts` and replace the example market configuration with your real:\n\nKeep 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.\n\nIf you want the agent to help, be explicit about the boundary:\n\n```\nConfigure this storefront for Denmark and Germany using the store IDs and currencies already\npresent in my local environment configuration. Read the Thor Next.js storefront guide first.\nKeep secrets server-side, do not invent missing IDs, and show me the exact files you plan to edit.\n```\n\nGenerate TypeScript types from the GraphQL documents:\n\n```\npnpm codegen\n```\n\nThen start the development server:\n\n```\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000). The middleware should redirect to a country-prefixed route such as `/dk`.\n\nYou 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.\n\nIf the catalog is empty, do not replace IDs until something appears. Ask the agent to trace the request context and check each layer:\n\n```\nThe Thor storefront returns no products for /dk. Diagnose this without changing data first.\nVerify the project slug, Storefront token, store ID, country, currency, price channel,\nproduct and variant status, publication window, price, and purchase availability.\nShow the evidence for the first failing layer.\n```\n\nThat prompt is intentionally diagnostic. It prevents a coding agent from hiding a configuration problem behind a UI workaround.\n\nThe storefront groups code by commerce domain, so you can change one experience without searching the entire repository:\n\n| What you want to change | Start here | \n|---|---|\n| Product queries | `src/lib/thorcommerce/storefront/queries/products.graphql` | \n| Product listing and detail UI | `src/features/products` | \n| Cart state and actions | `src/features/cart` | \n| Checkout steps | `src/features/checkout` | \n| Customer accounts | `src/features/account` and`src/lib/auth.ts` | \n| Market routing | `src/lib/thorcommerce/config.ts` ,`src/lib/request-context.ts` , and`src/middleware.ts` | \n| Shared UI | `src/components` | \n\nYou can now give the coding agent a visual and behavioral brief. For example:\n\n```\nRedesign the product listing and product detail pages for a minimal Scandinavian homeware brand.\nKeep the existing Thor Commerce data flow, variant selection, market-aware prices, availability,\nand add-to-cart behavior intact. Use the existing CSS Modules and accessible components.\nDo not add mock commerce data. Verify the result at mobile and desktop widths.\n```\n\nThe 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.\n\nSuppose 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.\n\nAsk the agent to start with the contract rather than a guessed field:\n\n```\nI want products to have a public, typed material specification that appears on the product page.\nRead Thor's metafields documentation and inspect the Admin and Storefront schemas.\nPropose the metafield definition, explain how its value is assigned through the product update input,\nadd the Storefront GraphQL selection, regenerate types, and render it accessibly.\nUse only a development project. Stop if the required owner type or field is not in the schema.\n```\n\nWhy this works:\n\n`.graphql` document and runs `pnpm codegen` instead of editing generated files.\nAfter any GraphQL selection changes, rerun:\n\n```\npnpm codegen\npnpm lint\npnpm build\n```\n\nCart and checkout deserve more than a visual spot-check. Thor calculates prices, discounts, stock, shipping eligibility, tax, and totals against the current commerce context.\n\nYour 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.\n\nGive your coding agent an outcome-based test brief:\n\n```\nVerify one complete test purchase in this storefront. Use an existing sellable variant and the\nconfigured test payment method. Confirm variant selection, add to cart, quantity update,\ncart persistence after refresh, shipping method selection, payment, order completion,\nand the resulting order in Thor Admin. Report evidence for each step and any untested dependency.\nDo not use production credentials or a live payment method.\n```\n\nAlso 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.\n\nBefore deployment, run:\n\n```\npnpm lint\npnpm build\n```\n\nThe 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.\n\nIf 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.\n\nWhichever platform you choose, verify:\n\nThe best prompts follow a simple loop:\n\nThis 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.\n\nBecause storefront presentation is decoupled from the commerce core, the same foundation can support:\n\nYou can begin with the reference storefront, then replace the visual system and extend one feature at a time without rebuilding the underlying commerce engine.\n\nYes. 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.\n\nYes. 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.\n\nIt 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.\n\nYes. 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.\n\nYes. The storefront uses standard Next.js patterns. Cloudflare configuration is included, but you can adapt the project for another compatible platform.\n\nIt 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.\n\nThor Commerce gives your coding agent something valuable: a real commerce model, typed API contracts, focused documentation, and a working storefront to extend.\n\nStart with the [Thor Commerce Next.js storefront](https://github.com/thor-commerce/next-thor-storefront), connect it to a development project, and make one verified improvement at a time.", "url": "https://wpnews.pro/news/how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai", "canonical_source": "https://dev.to/rsoe/how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai-2786", "published_at": "2026-09-13 21:27:58+00:00", "updated_at": "2026-09-13 21:51:12.971626+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Thor Commerce", "Next.js", "Claude Code", "Codex", "Cursor", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai", "markdown": "https://wpnews.pro/news/how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai.md", "text": "https://wpnews.pro/news/how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai.txt", "jsonld": "https://wpnews.pro/news/how-to-build-a-custom-ecommerce-store-with-thor-commerce-and-ai.jsonld"}}