ÃÛ¶¹ÊÓƵ

DocumentationCommerceÃÛ¶¹ÊÓƵ Commerce Optimizer Guide

[SaaS only]{class="badge positive" title="Applies to ÃÛ¶¹ÊÓƵ Commerce as a Cloud Service and ÃÛ¶¹ÊÓƵ Commerce Optimizer projects only (ÃÛ¶¹ÊÓƵ-managed SaaS infrastructure)."}

Set up your storefront

Last update: Thu Aug 07 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

This tutorial provides detailed instructions for setting up and using ÃÛ¶¹ÊÓƵ Commerce Storefront powered by Edge Delivery Services to create a performant, scalable, and secure Commerce storefront powered by data from your ÃÛ¶¹ÊÓƵ Commerce Optimizer instance.

TIP
Fast track the storefront set up process by using the Site Creator tool to set up your storefront code repository and document author environment
automatically. Then, you can use these instructions to understand how the storefront was created, and learn more about the components available to you.

Prerequisites

  • Ensure that you have a GitHub account (github.com) that can create repositories and is configured for local development.

  • Learn about the concepts and workflow to develop Commerce storefronts on ÃÛ¶¹ÊÓƵ Edge Delivery Services by reviewing the Overview in the ÃÛ¶¹ÊÓƵ Commerce Storefront documentation.

  • Set up your development environment

Set up your development environment

Install Node.js and the Sidekick browser extension required to develop and test your ÃÛ¶¹ÊÓƵ Commerce Optimizer storefront on Edge Delivery Services.

Install Node.js

Install Node Version Manager (NVM) and the required Node.js version (22.13.1 LTS).

  1. Install Node Version Manager (NVM).

    code language-bash 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

  2. Install Node.js and NPM. For more information, see .

    code language-bash 
    nvm install 22
    code language-bash 
    npm install -g npm

  3. Verify the installation.

    code language-bash 
    npm -v
TIP
Additional resources for extending and customizing your ÃÛ¶¹ÊÓƵ Commerce Optimizer solution are available through App Builder for ÃÛ¶¹ÊÓƵ Commerce and API Mesh for ÃÛ¶¹ÊÓƵ Developer App Builder. For access and usage information, contact your ÃÛ¶¹ÊÓƵ account representative.

Install Sidekick

Install the Sidekick browser extension to edit, preview, and publish content to the storefront. See .

Create your storefront

The storefront you create for your ÃÛ¶¹ÊÓƵ Commerce Optimizer project uses a customized version of the ÃÛ¶¹ÊÓƵ Commerce on Edge Delivery Services Storefront boilerplate. The boilerplate is a set of files and folders that provide a starting point for storefront development. This setup process is different than the standard setup process for an ÃÛ¶¹ÊÓƵ Commerce on Edge Delivery Services Storefront.

NOTE
This tutorial uses macOS, Chrome, and Visual Studio Code as the development environment. The screen captures and instructions reflect that setup. You can use a different operating system, browser, and code editor, but the UI you see and the steps you take vary accordingly.

Workflow overview

Follow these steps to set up a storefront to use with ÃÛ¶¹ÊÓƵ Commerce Optimizer.

  1. Create a code repository–Create a GitHub repository from the ÃÛ¶¹ÊÓƵ Commerce + Edge Delivery Services boilerplate template. Include all branches from the source repository.
  2. Update the storefront boilerplate–Update the custom boilerplate template on the aco branch to connect your content folder to the storefront.
  3. Deploy changes–Overwrite the code on the main branch with the updated code from the aco branch.
  4. Add the CodeSync app–Connect your repository to the Edge Delivery Service. Do not connect the Code Sync app until you have completed the source code customization and have pushed the code to the main branch.
  5. Add content–Use the demo content clone tool to create and initialize your storefront content in the Document Author environment hosted on https://da.live.
  6. Preview demo site–Connect to your storefront site to view the sample content and data from the ÃÛ¶¹ÊÓƵ Commerce Optimizer demo instance.
  7. Develop in your local environment–Install the required dependencies. Start the local development server, and update the storefront configuration to connect to the ÃÛ¶¹ÊÓƵ Commerce Optimizer instance that ÃÛ¶¹ÊÓƵ provisioned for you.
  8. Next steps–Learn more about managing and displaying content and data in the storefront.

Step 1: Create site code repository

Create a GitHub repository for the site boilerplate code for your storefront using the Edge Delivery Services + ÃÛ¶¹ÊÓƵ Commerce Boilerplate template.

  1. Log in to your GitHub account.

  2. Navigate to the GitHub repository.

  3. Select Use this template, and then select Create a new repository from the drop-down menu.

    Create github repo from storefront boilerplate template {width="700" modal="regular"}

    The repository configuration page displays.

    Configure github repo to pull all branches from boilerplate repo {width="700" modal="regular"}

  4. Complete the configuration form with the following details:

    • Repository template—hlxsites/aem-boilerplate-commerce (default).
    • Owner—Your organization or account (required).
    • Repository name—A unique name for your new repo (required).
    • Description—A brief description of your repo (optional).
    • Public or Private—ÃÛ¶¹ÊÓƵ recommends public (default).

  5. Select Create repository.

    After several minutes, your new repository opens.

    Ignore any pull request notifications displayed in the GitHub user interface.

Step 2: Update the storefront boilerplate

You need the following information to update the storefront boilerplate code:

  • GitHub repository URL from Step 2— github.com/{ORG}/{SITE}

    • {ORG} is the organization name or username for the repository

    • {SITE} is your repository name

  • Content folder URL from Step 1— https://drive.google.com/drive/folders/{YOUR_FOLDER_ID}

    {YOUR_FOLDER_ID} is the ID of the folder that you created with the sample content data.

  1. Clone the repository to your local machine.

    code language-bash 
    git clone https://github.com/{ORG}/{SITE}.git

    If you encounter errors when cloning the repository, see in the GitHub documentation.

  2. Open the repository in your terminal or IDE.

  3. Create your configuration file by copying the default-fstab.yaml file to fstab.yaml.

    code language-bash 
    cp default-fstab.yaml fstab.yaml

  4. Update the mountpoint in the storefront configuration file to point to your content URL.

    1. Open the fstab.yaml configuration file.

      code language-yaml 
      mountpoints:
  /:
    url: https://content.da.live/{org}/{site}/
    type: markup

folders:
 /products/: /products/default

    2. Replace the {ORG} and {SITE} strings with the values for the GitHub repository that you created for your boilerplate code.

      For example, the updated code should look like this.

      code language-yaml 
      mountpoints:
  /:
    url: https://content.da.live/owner-name/aco-storefront/
    type: markup

    3. Save the file.

Configure the Sidekick extension

  1. Add the project configuration for the Sidekick extension. This configuration ensures that Sidekick is available to manage content for your storefront project.
NOTE
Make sure that you have installed the in your browser.

  1. Create a new directory tools/sidekick.

    code language-shell 
    mkdir tools/sidekick

  2. Copy the demo-sidekick.json file in the root directory to the tools/sidekick directory and rename it to config.json.

    code language-shell 
    cp demo-sidekick.json tools/sidekick/config.json

  3. Customize the Sidekick configuration for your site.

    From tools/sidekick/ directory, edit the config.json file.

    accordion
    Sidekick configuration file
    code language-json 
    {
  "project": "My Project",
  "editUrlLabel": "Document Authoring",
  "editUrlPattern": "https://da.live/edit#/{{org}}/{{site}}{{pathname}}"
}

  4. Update the url key values with the values for your GitHub repository.

    • Replace the {{ORG}} string with the organization or username for your repository.

    • Replace the {{SITE}} string with the repository name.

    • The pathname variable is populated by the system.

    accordion
    Example of updated configuration file

    If your GitHub repository is named aco-storefront and your organization is early-adopter, the updated URL should look like this:

    code language-json 
    {
  "project": "My Project",
  "editUrlLabel": "Document Authoring",
  "editUrlPattern": "https://da.live/edit#/aco-storefront/early-adopter{{pathname}}"
}

  5. Save the file.

Step 3: Deploy changes

To use the customized storefront boilerplate code, overwrite the code on the main branch with your updates.

  1. From your editor or IDE, commit and save the files you updated.

    code language-bash 
    git add .

  2. Verify that you are committing the two updated files.

    code language-bash 
    git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
 (use "git restore --staged <file>..." to unstage)
     new file:   fstab1.yaml
     modified:   tools/sidekick/config.json

  3. Commit the changes.

    code language-bash 
    git commit -m "Update storefront boilerplate for ÃÛ¶¹ÊÓƵ Commerce Optimizer"

  4. Apply your changes.

    code language-bash 
    git push

Step 5: Add the AEM Code Sync app

Connect your repository to the Edge Delivery Service by adding the AEM Code Sync GitHub app to your repository.

IMPORTANT
Do not connect the Code Sync app until you have uploaded the updated boilerplate code to the main branch of your GitHub repository.

  1. Open the configuration page.

  2. Select Configure, then authenticate with the organization or account that contains the repository you created.

  3. From the form, choose Only select repositories, and then select the repository you created.

  4. Select Install to add the AEM Code Sync app to your repository.

    You should see a message that the app was successfully installed.

Step 6: Add content

Create and initialize your storefront content in the Document Author environment hosted on https://da.live using the Site Creator tool. This tool imports the sample content into the Document Author environment and completes the content preview and publish process for all documents in the sample content. The sample content includes the page layouts, banners, labels, and other elements to populate your storefront.

  1. Open the

  2. Confgure your repository:

    • Select Use Existing Repository.
    • Enter the Organization/Username for your storefront boilerplate project.
    • Enter the Repository Name.

  3. Import, preview, and publish the content to the Document Author environment by selecting Create site.

    AEM demo content clone tool {width="700" modal="regular"}

    After the site is created, you can use the links in the Edit content and View Site sections to explore the demo storefront.

    The main links to your content and site follow these formats:

    • Root content folder— https://da.live/#/{ORG}/{SITE}
    • Site preview— https://main--{SITE}--{ORG}.aem.page/
    • Site production:— https:/main--{SITE}--{ORG}.ae.live/

  4. Open the root content folder link to view the content.

    Storefront Document Author environment {width="700" modal="regular"}

    note tip
    TIP
    In the side navigation, use the Learn and Discover links to access learning resources for managing your site and site content.

Step 7: Preview demo site

Verify that both the sample content and the data from the ÃÛ¶¹ÊÓƵ Commerce Optimizer demo instance are displayed correctly.

  • Sample content is served from the content folder in the Document Author environment. It includes the page layouts, banners, and labels for your site.
  • Sample data is served from the ÃÛ¶¹ÊÓƵ Commerce Optimizer demo instance. Data includes product data with product attributes, images, product descriptions, and prices populated based on the header values specified in the storefront configuration file, config.json.

Connect to your site to view sample content and data

  1. View your site by navigating to https://main--{SITE}--{ORG}.aem.live.

    Replace {ORG} and {SITE} with the organization and name for your boilerplate repository.

    ACO storefront site with boilerplate {width="700" modal="regular"}

    If the page returns a 404, verify the following:

  2. View the sample catalog data coming from the Commerce Optimizer default instance.

    1. In the storefront header, click the magnifying glass to search for tires.

      View product list page {width="675" modal="regular"}

    2. Press Enter to view the search results page.

      View search results page {width="675" modal="regular"}

      The search results page components are defined by the search content document. The search results data is populated based on the storefront configuration in config.json.

    3. View the product details page by selecting any tire product on the page.

      View product details page {width="675" modal="regular"}

      The product details page components are defined by the default content document in the product folder.

Step 8: Develop in your local environment

In this section, you update the storefront configuration from your local development environment.

  • Update the storefront configuration to connect to the GraphQL endpoint for the ÃÛ¶¹ÊÓƵ Commerce Optimizer instance that ÃÛ¶¹ÊÓƵ provisioned for you.
  • Update the header values to retrieve data from your instance.

Start local development

  1. In your IDE, checkout your main branch, and reset it to the last commit on the remote branch.

    code language-bash 
    git checkout main
git reset --hard origin/main

  2. Install the required dependencies.

    code language-bash 
    npm install

  3. Start the local development server.

    code language-bash 
    npm start

    The first page of your boilerplate storefront should be visible in your browser at http://localhost:3000.

    Configure github repo to pull all branches from boilerplate repo {width="700" modal="regular"}

Update the storefront configuration

Update the storefront configuration file and preview the changes in your local development environment.

  1. In your IDE, update the storefront configuration to connect to the ÃÛ¶¹ÊÓƵ Commerce Optimizer instance that ÃÛ¶¹ÊÓƵ has provisioned for you.

    1. Open the config.json file.

    2. Update the following values using the endpoint for your ÃÛ¶¹ÊÓƵ Commerce Optimizer instance:

      • commerce-endpoint–Replace the existing value with your endpoint URL.

        code language-json 
        "commerce-endpoint": "https://na1-sandbox.api.commerce.adobe.com/{tenantId}/graphql"

      • ac-environment-id—Replace the existing value with the tenant ID from your endpoint URL.

        code language-json 
        "ac-environment-id": "{tenantId}"

    3. Save the file.

      If your local preview is working correctly, the updates are applied to your local storefront.

  2. Check the site to see the results of the configuration change.

    1. In the browser, navigate to http://localhost:3000 and refresh the page.

    2. In the storefront header, click the magnifying glass to search for tires.

      Search for tires {width="675" modal="regular"}

    3. Press Enter to display the Search Results page.

      Empty search results with invalid header values {width="675" modal="regular"}

      The search doesn’t return any results because the header values in your storefront configuration file are based on the default instance. Now that the configuration points to the ÃÛ¶¹ÊÓƵ Commerce Optimizer instance provisioned for you, those values are invalid.

Next steps

See the Storefront and Catalog Administrator end-to-end use case to learn more about managing and displaying content and data in the storefront.

Related Articles
See the ÃÛ¶¹ÊÓƵ Commerce Storefront documentation to learn more about updating site content and integrating with Commerce frontend components and backend data.
recommendation-more-help
0c009cf6-d957-4a6a-b642-3577df53e8cb