Build a storefront from scratch

Ask about this Page
Copy for LLM
View as Markdown

Learn how to build a commerce storefront with the AI plugin.

What you'll build

By following this tutorial, you will build from scratch a working commerce storefront on Next.js 16, connected to your commercetools Project.

The storefront includes product listing, product detail pages, search, faceting, cart, checkout, and customer authentication.

The agent scaffolds and wires it. You go from an empty folder to a storefront running on localhost, then to a live deployment, without hand-writing the integration plumbing. Most of the work is the agent's. Yours is to supply credentials, run a few commands, and read the output.

Before you start

To start building your storefront, you need:

Build the storefront

1: Create an API client

  1. In the Merchant Center, go to Settings > Developer settings > API clients > Create new API client.
  2. In the Name field, enter a name that will help you recognize your client later, like storefront-dev.
  3. From the Scopes drop-down, select the Frontend B2C or Frontend B2B templates. Then, in the Manage column for scopes, ensure Checkout sessions and Orders are selected. That gives you a Frontend client, which is the one you want.
    Ensure that the Manage Project Scope is not selected, as you must not use it. For further information, see Security and best practices.

  4. Copy the credentials somewhere safe as you'll need them for steps 6 and 8.

2: Activate the Product Search API in the Merchant Center

If you did not activate the Product Search API during Project setup before starting, do it now.
In the Merchant Center, go to Settings > Project Settings > Storefront Search, and activate the Product Search option.

3: Configure Checkout in the Merchant Center

To use your payment service providers (PSPs), configure Checkout from the Merchant Center. For more information, see Configure Checkout.

4: Make your project folder

mkdir my-storefront && cd my-storefront
git init

5: Install the plugin

Install the plugin

In any Claude Code session:

/plugin marketplace add commercetools/commercetools-skills
/plugin install commercetools@commercetools
Reload plugins

If you've updated the plugin or installed it in another window and need the current session to pick up the latest version:

/reload-plugins
Claude Desktop
Customize -> Personal plugins -> Create plugin -> Add marketplace -> add commercetools/commercetools-ai-plugins

then click on the plugin and click "Install"

6: Configure the MCP servers

Two connectors come with the plugin:

  • commercetools-knowledge: handles live docs, schema lookup, and query validation. It's public, doesn't require a key, and is already active.
  • commerce-mcp is the optional one that lets the agent call your own project's APIs. To switch it on, export your step 1 credentials into your shell before you launch the agent:
export CLIENT_ID={clientID} \
       CLIENT_SECRET={clientSecret} \
       PROJECT_KEY={projectKey}\
       AUTH_URL=https://auth.{region}.commercetools.com \
       API_URL=https://api.{region}.commercetools.com

7: Run your first prompt

With the plugin in place, you must tell the agent to scaffold the project. A prompt like the following works:

Generate a complete B2C storefront connected to commercetools.

Scope:
- home page
- product listing + facets (use the Product Search API)
- product detail
- cart
- checkout using Checkout Browser SDK
- customer authentication and account area
- search page

The agent runs and creates the Next.js app, installs dependencies, wires up locale routing, and builds each feature from the skills. Let it work, it already knows the structure it's supposed to follow.

8: Drop in your credentials

The scaffold creates an environment file in the app directory, fill in your step 1 credentials:

# .env
CTP_PROJECT_KEY={projectKey}
CTP_CLIENT_ID={clientID}
CTP_CLIENT_SECRET={clientSecret}
CTP_AUTH_URL=https://auth.{region}.commercetools.com
CTP_API_URL=https://api.{region}.commercetools.com
CTP_SCOPES=<your-frontend-scopes>
SESSION_SECRET=<generate-this>

The session secret has to be at least 32 characters in production, so generate a real one rather than typing something in:

openssl rand -base64 48

9: Run it

npm install
npm run dev
Open http://localhost:3000. You should see your products, browse categories, add items to the cart, and walk through checkout in your live commercetools Project.

10: Deploy

When you're ready to put it online, the plugin's deploy commands handle it safely. Run /deploy-vercel or /deploy-netlify. Each one checks that you're deploying with a Frontend API client and not a manage_project one. Then confirms that your SESSION_SECRET is set and hands the actual deploy to Vercel's or Netlify's official agent skill. Read Security and best practices before you do this.
That's it. If you want to customize beyond the defaults or learn more about the architecture, see Tech stack and architectural choices behind skills. Also, Security and best practices is required reading when you move past local development.