Build a storefront from scratch

Ask about this Page
Copy for LLM
View as Markdown

Learn how to build a commerce storefront from scratch with the commercetools 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.

Prerequisites

To start building your storefront, you need:

Set up your commercetools Project

If you don't have a commercetools Project yet, this is how you can create one:

  1. Access the Merchant Center, then click the profile icon and select Manage projects.
  2. Click Create new project:
    • To start with an empty Project and enter or import your own data, select Start from scratch.
    • To use sample data, select Start with sample data. Then, select either the B2C or B2B dataset.
  3. Enter the details for your Organization and Project, and then click Complete.
    • Organization name: select the Organization to which the Project belongs. By default, signing up for an account and then accessing the Merchant Center will automatically create an Organization for you.
    • Project name: enter the name for your Project.
    • Project key: enter an identification key for your Project. By default, the Merchant Center suggests a Project key, but you can replace it as needed. The key must be unique and contain between two and 36 characters. It can contain only alphanumeric characters (a-Z, 0-9), underscores (_), and hyphens (-). The key must not contain any of these reserved words: local, admin, or config.
  4. Click Complete.

Build the storefront

1: Create an API client in the Merchant Center

  1. In the Merchant Center left-hand menu, 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, for example, storefront-dev.
  3. From the Scopes drop-down, select the Frontend B2C or Frontend B2B templates. Then, in the Manage column, ensure the Checkout sessions and Orders Scopes are selected. This creates a Frontend client, which is the one you need.
    Ensure that in the Manage column, the Project Scope is not selected, as you must not use it. For further information, see Security and best practices.
  4. Copy your client credentials and save them, or download an .env file containing them. You'll need your credentials in steps 6 and 8.

2: Activate the Product Search API in the Merchant Center

To activate the Product Search API, follow these steps:

  1. In the Merchant Center left-hand menu, go to Settings > Project settings > Storefront Search.

  2. Click the edit button.

  3. Activate the Product Search option.
  4. Click Save, then click Start indexing now.

3: Configure Checkout in the Merchant Center

If you are building your storefront for test or demo purposes, you can just confirm permissions and a Subscription as follows, and then move to step 4.

  1. In the Merchant Center left-hand menu, go to Checkout and click Get started.
  2. Click Let's proceed to handle the required confirmation.
  3. Click Confirm creation.
OPTIONAL: If you want to build a fully fledged storefront and use your payment service providers (PSPs) for a working checkout flow, you must create Connectors and Applications for them. For more information, see Connectors and Applications.

4: Create your storefront project folder

Now you must create a folder on your computer where all the files for your storefront project will live, and prepare the folder for version tracking. To do so, follow these steps:

  1. Open your computer's terminal window:

    • macOS: press Cmd + Space, type Terminal, and press Enter.
    • Windows: press the Windows key, type Terminal or PowerShell, and press Enter.
    • Linux: press Ctrl + Alt + T, or search for Terminal in your applications menu.

  2. Decide where on your computer you want your storefront project folder to sit (for example, your Desktop or Documents folder).

    Then, copy the following command and paste it into the terminal window and press Enter.
    In the command, we use Desktop as an example, but you can store your project folder where you prefer. If you want to store it in a different directory, replace Desktop with the name of the directory.
    Move to the Desktop directorybash
       cd ~/Desktop
  3. Copy the following command and paste it into the terminal window, then press Enter.
    In the command, we use the name my-storefront as an example, but you can call the project folder anything you like. If you want to use a different name, replace my-storefront with your name.
    Create the my-storefront project folder and move to itbash
       mkdir my-storefront && cd my-storefront
  4. Copy the following command and paste it into the terminal window, then press Enter.
    Initialize version tracking for the project folderbash
      git init

5: Install the plugin with your coding agent

Open your coding agent and install the commercetools AI plugin by following the related instructions. Install the plugin in the project folder that you created in the previous step.

Install the plugin

In any Claude Code session:

/plugin marketplace add commercetools/commercetools-ai-plugins
/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

The plugin includes two MCP servers to power your coding agent:

  • Knowledge MCP: It does not require any configuration as it is already active. It handles live documentation, schema lookup, and query validation.
  • Commerce MCP: It is optional for building the storefront and requires your client credentials from step 1. It lets the agent call your commercetools Project's APIs. For example, you could use it to let the agent read the product catalog in your Project and decide what'd be best to showcase on the homepage.

If you don't need to use the Commerce MCP server, you can move to step 7. Otherwise, to configure the Commerce MCP server:

  1. Open your computer's terminal.

  2. Copy the following command and paste it into the terminal window. Then, replace the placeholders (for example, {clientID}) with the client credentials that you generated and saved in step 1.
    Export your credentials to activate the Commerce MCP serverbash
    export CLIENT_ID={clientID} \
      CLIENT_SECRET={clientSecret} \
      PROJECT_KEY={projectKey}\
      AUTH_URL=https://auth.{region}.commercetools.com \
      API_URL=https://api.{region}.commercetools.com
  3. Press Enter.

    After configuring the Commerce MCP, you might need to restart the conversation with your coding agent for it to recognize the newly added credentials.

7: Run your first prompt and scaffold the project

Open your coding agent and tell it to scaffold the storefront project by using a prompt similar to the following.

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
While running, the agent might ask you to confirm certain decisions. For example, which frontend framework to use to scaffold the project, in such a case, select Next.js.
If you want to be asked for confirmations and be in control of decisions, let the agent run and ask you questions. Otherwise, if you are building the storefront for test or demo purposes, you can instruct the agent not to ask for confirmation and to act on its own by adding a statement to your prompt.

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 that it should follow.

8: Configure environment variables

The scaffold creates an .env file similar to the following in the site folder. Edit the file by entering the credentials you generated in step 1 and a session secret that you can generate as described below. Sometimes, the file may already be partially or fully populated with your credentials and the secret. In that case, you can leave it as is if the values are correct.
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-if-not-present>

To generate a session secret:

  1. Open your computer's terminal

  2. Copy and paste the following command in the terminal window, and press Enter. The session secret has to be at least 32 characters long. This command generates a 64-character secret.
    Generate a random 64-character secretbash
    openssl rand -base64 48
  3. Copy the generated session secret and add it to the .env file as the value for SESSION_SECRET. Then, save the file.

9: Run the storefront locally

You can now run the storefront on your local machine.

  1. Open your computer's terminal.

  2. Copy and paste the following command in the terminal window, and press Enter.
    Install and run the storefront locallybash
    npm install
npm run dev
  3. Open your browser and enter http://localhost:3000 in the address bar. You should see your storefront and be able to navigate it.

10: Deploy the storefront

When you're ready to move your storefront off your local machine, the plugin handles the deployment for you, including a few automatic safety checks before anything goes live.

Open your coding agent and run either the /deploy-vercel or /deploy-netlify command. Before deploying, the command automatically verifies that:
  • Your API connection is set up safely: it confirms you're using a read-only storefront connection, not one with permissions to modify your commercetools Project.
  • Your storefront is secured: it checks that your SESSION_SECRET is configured.

Once both checks pass, the command hands off to Vercel's or Netlify's own deployment process. That's it, your storefront is deployed.

If you plan to deploy your storefront to production, ensure you read Security and best practices first.