Multistore

Multistore setup

What is multistore?

Multistore refers to the ability to run multiple storefronts from a single codebase and content repository. This is useful for:

Localization: Serving different languages and currencies (e.g., English/US, French/Canada) from the same site, with localized content and commerce data.
Multiple Brands or Regions: Operating several brands or regional storefronts, each with their own configuration, but sharing core code and content.

There are two main approaches to multistore:

Multiple Domains: Each domain points to a different commerce backend or configuration, but shares the same code and content.
Subfolders (Root Folders): A single domain with subfolders (e.g., /en/, /fr/) for each locale or store. Each subfolder can have its own localized content and commerce configuration.

Key features:

Editorial and Commerce Localization: Editorial content (pages, blocks) and commerce data (products, prices, currencies) are both localized.
Automated Translation Tools: Tools are provided to automate translation of content and manage updates across languages.
Configurable Headers: Storefronts can send different headers to the commerce backend to select the correct store, language, and currency.

How does multistore configuration work?

Config Files: Each store or locale is defined in configuration files, specifying which headers to send to the commerce backend, which content folders to use, etc.
Store Switcher: Out-of-the-box, a store switcher UI is provided so users can switch between stores/locales on the frontend.
Automatic Link Management: Links are automatically updated to point to the correct localized version as users navigate the site.

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.

Big picture

Multistore 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 Document Authoring Content file structure of a multistore is shown below.

Directory/en/ — English store (Default root language)
- placeholders/** — Stores JSON files for text and UI components for the English US store.
- index — The home page of the English US store.
- store-switcher — Manages the list of stores and their URL for the English US store.
Directory/en_ca/ — English Canadian Store
- placeholders/** — Defines JSON files for text and UI components for the Canadian store.
- index — The home page of the English Canadian store.
- store-switcher — Manages the list of stores and their URL for the Canadian store.

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 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/#nolocal)
- Canada (CAD)
  - [Canada (EN)](https://main--aem-boilerplate-commerce--hlxsites.aem.page/en_ca/#nolocal)

Important: The storefront will automatically update links relative to the storefront’s root path. For links you don’t want to be localized (such as a store switcher links), add the hash #nolocal to ensure these remain absolute to the site. This is particularly useful for store switchers as you want to navigate to different store paths within the same site.

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 documents hosted on https://da.live (Document Author environment), SharePoint .docx, or Google that are used to generate the store view pages. These files should be localized for the desired region and language.

Placeholders

In the placeholders directory, you will find JSON files that define reusable variables for text and UI components. Each drop-in component has its own placeholders file— cart.json, checkout.json, pdp.json. These files replace variables in your content files with text values.

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

Configuration Service

If your project uses the Configuration 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 configuration

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).

Add a new store

Create an en_ca store view in the Commerce Admin and perform the following steps in your project.

Create the /en_ca/ folder under the project root in your content folder. You can name this folder anything you want, as long as it’s unique and can be used in a web address. For example, instead of Canada (English), you can use ca_en.
Copy the store switcher, placeholders directory, and document files from the /en/ directory to the /en_ca/ directory.

Update Content Files

Next, localize or translate the files in your project.

Translate or localize content files in the /en_ca/ folders.
Make sure labels in the placeholder JSON files are correctly translated. Update each component’s placeholders file as needed—cart.json, checkout.json, pdp.json.

Update Storefront configuration

Update the fstab.yaml file — or the fstab section of your site config — to include the new folder mapping for the /en_ca/ store view. This should map to the appropriate content path. For example, /en_ca/products/ should map to /en_ca/products/default.
Update the config.json file - or the public section of your site config - to include a new entry under in the public object for /en_ca/. Use this section to define store-specific values such as headers, analytics, and more, if they differ from the default. Make sure the key matches the folder path of your store view. For example, the /en_ca/ key for your Canadian store). Values in this object will override those in the default configuration.
If you are using the Config Service, read the api documentation to learn how to publish your updates to the Config Service for your site.

Preview and validate

Finally, preview and publish the new store view.

Preview all files in the updated folder /en_ca/ with AEM Sidekick.
Validate the storefront experience by accessing the new language/region and testing the rendering, navigation, and data accuracy.
Publish the updated folder using the AEM Sidekick folder when ready.
Update the store-switcher content document to include a link to the new store view.