Multi-store setup

Adobe Commerce uses a hierarchical structure to manage multiple stores within a single instance. This structure consists of three levels: websites, stores, and store views. Localization is managed at the store view level, allowing merchants to present the store in different languages and apply the proper currency.

To maintain storefronts that implement Edge Delivery Services, you must be familiar with its building blocks. The following topics describe the EDS features.

• Authoring and Publishing Content
• Placeholders
• Adobe Commerce Configuration Scope
• Storefront Configuration
• Folder Mapping

Big Picture

Multi-store refers to a streamlined architecture that enables managing multiple stores with unique catalogs and localization while leveraging a shared code base and unified content delivery. The content hierarchy follows Edge Delivery Services best practices, emphasizing a single-tier structure.

Content is organized primarily by language. US English files should be placed in the en directory of the project root. All other language- and region-specific files should be placed in a directory that is named in the format *region-code_language-code*. For example, the /en/ directory contains data for the US market, while the /en_ca/ directory contains data for Canada. French content should be placed in directories with names like fr_fr for France and fr_ca for Canada.

The Sharepoint file structure of a multi-store is shown below. Remove the .docx and .xlsx extensions for Google Drive files.

Default files are provided in the sample content. These files can be customized to suit your needs.

Store-specific files

The content, placeholders, and store switcher files help define the experience in each store view as described here.

Store Switcher

Each store view has its own store-switcher document file called a fragment. This fragment provides the list of stores to select from by language. The store-switcher component renders a button in the footer that opens a modal containing the stores listed in this document.

Start by creating a store-switcher.docx file containing a bulleted list inside each store view root folder. Each line must define the display name of your store with an active link to the store, as shown below:

**Select a store:**

- United States (USD)
  - [United States (USD)](https://main--aem-boilerplate-commerce--hlxsites.aem.page/en/)
- Canada (CAD)
  - [Canada (EN)](https://main--aem-boilerplate-commerce--hlxsites.aem.page/en_ca/)

Content files

The content files provide the structure of the pages served to your shoppers. They are located in the store view directories and contain the content for each store view. These files are typically SharePoint .docx or Google document files used to generate the store view pages. These files should be localized or translated into the desired language.

Placeholders

The placeholders.xlsx file stores reusable variables for text and UI components. This file is used to define the text that is displayed on your storefront. The placeholders.json file is generated from this file and is used to replace the variables in your content files.

If you want to reuse placeholders.xlsx files from another store view, use bulk metadata (https://www.aem.live/docs/bulk-metadata). You can also create a placeholders-overrides.xlsx file to override the default text values in the original document, then add a metadata block to the page to apply the overrides file, as shown here:

To override the default behavior of loading placeholders.xlsx from the store view directory, create a metadata.xlsx file with contents similar to the following:

• URL: Defines the URL pattern for pages where metadata should be applied. Wildcards can match groups of pages to which the metadata is applied. For example, /en/** matches all pages in the /en/ (English) directory.
• placeholders: Specifies the path to a placeholders.json file that provides key-value mappings for dynamic content replacement. You can specify a second file to act as an override, with its values taking precedence over the previously listed files.

Storefront Configuration

Folder Mapping

Product Detail Pages (PDP) are mapped to a single document at products/default. When adding a new store view, you’ll need to add a corresponding folder mapping for the new URLs.

fstab.yaml

If your project uses a fstab.yaml file, add the new store view mapping under the folders: section, like this:

mountpoints:
  /: https://example.mountpoint.com/:f:/r/sites/myproject

folders:
  /en/products/: /en/products/default
  /en_ca/products/: /en_ca/products/default

Config Service

If your project uses the Config Service, you must update the configuration to add the new store view mapping under the folders: section, like this:

{
  "folders": {
    "/en/products/": "/en/products/default",
    "/en_ca/products/": "/en_ca/products/default"
  }
}

To learn more about the Config Service, please see aem.live’s documentation or read the api documentation to learn how to publish your updates to the Config Service for your site.

Site Config

You must update your storefront config to include configuration overrides for the new store view. In this file, you’ll define store-view specific settings, such as service headers and analytics values. The key of each overridden object must match the root folder path of the corresponding store view. These values will be merged into the default configuration.

The analytics section contains the Adobe Commerce environment variables for the store view. These variables are used by the Analytics API. For more details, see Analytics.

{
  "public": {
    "default": {
      // default configuration
    },
    "/en/": {}, // inherits the default
    "/en_ca/": {
      "headers": {
        // overrides values from the default headers
      },
      "analytics": {
        // overrides values from the default analytics configuration
      }
    }
  }
}

Step-by-Step

These steps show you how to add a new English Canadian store view (en_ca) similar to the default English store (en).