Multi-Store Implementation Walkthrough

This tutorial provides a comprehensive walkthrough of setting up multi-store functionality for an Adobe Commerce storefront using Edge Delivery Services. It demonstrates the complete process from initial planning to final validation, using a real-world scenario where the Acme brand expands from the United States to the Canadian market.

Overview

In this walkthrough, we’ll demonstrate how to:

Set up the necessary file structures for multi-store views
Configure store views in Adobe Commerce Admin
Update storefront configuration files
Preview and publish localized content
Configure the store switcher for proper store view display

Scenario

The Acme brand is expanding its international presence and wants to target the Canadian market with two new locales:

Canadian English (en-ca)
Canadian French (fr-ca)

Prerequisites

Before beginning this implementation, ensure:

Your storefront repository is linked to Document Authoring environment (da.live) via Edge Delivery Services
You have access to Adobe Commerce Admin for store view configuration
Your fstab.yaml file is properly configured
Your config.json file is linked to the Adobe Commerce instance

Implementation Steps

Verify Environment Setup

Before implementing multi-store functionality, confirm your environment is properly configured.

Check the fstab.yaml file in your repository to ensure it’s linked to the Document Authoring environment at da.live, as described in multistore/#folder-mapping
Verify the config.json file is connected to your Adobe Commerce instance to enable content preview, publishing, and editing as described in multistore/#site-config

Create Content Folder Structure

Set up the folder structure in your Document Authoring environment to support the new store views.

Navigate to the connected content folder in da.live.
Create the Canadian English folder:
- Select “New folder”
- Name it en-ca
Create the French folder:
- Select “New folder”
- Name it fr-ca
Copy content from the main root folder into each new store view folder:
- Select all content from the main root folder
- Copy the content
- Navigate to the en-ca folder and paste
- Repeat for the fr-ca folder

Configure Adobe Commerce Store Views

Create the corresponding store views in Adobe Commerce Admin to match your content folder structure.

Access Adobe Commerce Admin and navigate to Stores > Settings > All Stores.
Create the Canadian English store view:
- Follow the store view creation process
- Configure as: one website, one store, one store view
- Set the store view code to match your folder name (en-ca)
Create the Canadian French store view:
- Repeat the process for the French locale
- Set the store view code to match your folder name (fr-ca)

Update Storefront Configuration

Modify your project’s configuration files to support the new store views.

Update the fstab.yaml file to include new folder mappings:

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

folders:
/en-ca/products/: /en-ca/products/default
/fr-ca/products/: /fr-ca/products/default

Update the config.json file to include new entries under the public object:

{
  "public": {
    "default": {
    // default configuration
    },
    "/en-ca/": {
        "headers": {
           "all": {
              "Store": "en-ca"
           },
           "cs": {
              "Magento-Store-Code": "ca-store",
              "Magento-Website-Code": "base",
              "Magento-Store-View-Code": "fr-ca"
           }
        }
     },
      "/ca-en/": {
        "headers": {
           "all": {
              "Store": "ca-en"
           },
           "cs": {
              "Magento-Store-Code": "ca-store",
              "Magento-Website-Code": "base",
              "Magento-Store-View-Code": "en-ca"
           }
        }
     }
  }
}

Ensure header values match what was created in Adobe Commerce Admin store settings to properly connect store views to file structures.

Preview and Validate Content

Test your new store views to ensure proper functionality before publishing.

Push configuration changes to your storefront repository.
Return to the content files in both en-ca and fr-ca folders in da.live.
Preview content files:
- Navigate to the en-ca folder
- Open the index file
- Click “Preview” to test the store view
Verify configuration in browser:
- Check the URL structure includes the store view path
- Open browser Developer Tools
- Navigate to Application > Session Storage
- Verify the config shows the correct headers you added:
  - magento-store-code
  - magento-website-code
  - magento-store-view-code

Configure Store Switcher

Update the store switcher to properly reflect the current store view for customers.

Navigate to the store switcher file in the en-ca content folder.

Update the store switcher structure to prioritize the current store view:

Move “Canada English” to the top of the list
Ensure proper formatting and links
Example structure:

- Canada (CAD)
  - [Canada (EN)](https://your-site.com/en-ca/)
  - [Canada (FR)](https://your-site.com/fr-ca/)
- United States (USD)
  - [United States (USD)](https://your-site.com/en/)

Publish the updated store switcher:
- Click “Publish” on the store switcher file
- This updates the footer display for customers
Verify the store switcher display:
- Return to your preview of the Canadian English store
- Check that the store switcher now correctly shows the customer is on the Canadian English store view
- Confirm customers can see and select other available stores

Final Validation and Handoff

Complete the implementation with thorough testing and team coordination.

Test all store views to ensure:
- Proper URL structure
- Correct content loading
- Functional store switcher
- Accurate header configuration
Prepare for localization:
- Inform the marketing team that content folders are ready for translation
- Provide directory structure documentation
- Share access to the fr-ca folder for French translations
Document the implementation for future reference and team knowledge sharing.

Key Configuration Details

Headers Configuration

The headers section in your config.json is critical for proper store view functionality:

magento-store-code: Must match the store code from Adobe Commerce Admin
magento-website-code: Typically “base” for single-website setups
magento-store-view-code: Must match the store view code from Adobe Commerce Admin

Folder Structure Best Practices

Use clear, consistent naming conventions (e.g., en-ca, fr-ca)
Ensure folder names can be used in web URLs
Match folder names exactly with Adobe Commerce store view codes
Maintain the same content structure across all store views

Store Switcher Configuration

Each store view should have its own store-switcher file
Prioritize the current store view in the display order
Ensure all links point to the correct store view URLs
Test the switcher functionality across all store views

Next Steps

After completing this implementation:

Marketing Team Handoff: Share the content folders with your marketing team for localization and translation work
Content Translation: Begin translating content in the fr-ca folder for the French Canadian market
Testing: Conduct thorough testing across all store views and customer scenarios
Launch Planning: Coordinate the launch of new store views with marketing and business teams

This multi-store setup provides a solid foundation for international expansion while maintaining a unified codebase and streamlined content management process.