Skip to content
Adobe Commerce Storefront

Storefront configuration

In this section, you’ll learn how Commerce blocks in your storefront connect to a Commerce backend using values from either your site’s public config or a config.json file in your code repo.

The configuration is organized into several key sections:

  • Endpoints - GraphQL endpoints for Commerce and Catalog Services
  • Headers - HTTP headers required for API authentication and store context
  • Analytics - Store and environment metadata for tracking and reporting
  • Plugins - Configuration for various Edge Delivery Services plugins and features
  • Multistore - Settings for multiple store views and internationalization

When implementing your own project, you must update the configuration values with:

  • The Adobe Commerce and Catalog Service GraphQL endpoint that you configured as part of the content delivery network (CDN) setup.
  • The header values specific to your Adobe Commerce Catalog Services environment.

If you set up your storefront using the boilerplate code, the template repo provides you with a demo-config.json file in the root folder. This file contains the environment values for a Commerce backend including GraphQl endpoints and headers.

If you set up your site using the Site Creator Tool, the config.json file is created and added to the GitHub repository created for the boilerplate code. You can review and update the default values in the config.json file after the process completes.

Vocabulary

Storefront configuration

A JSON object that maps properties and values used by the Commerce boilerplate.

The storefront configuration is a JSON object which lives in the config-service and contains the connection settings for your Commerce blocks. The boilerplate repo also contains a demo-config.json file that can be renamed to config.json instead of using the config service, although we suggest using the config service.

At the root, there is a public property which should not be changed, and a nested default object. This default object is the root level configuration that is used for your storefront. The config object contains properties and values which correspond to a specific setting or usage in your Commerce backend.

If you use aem.live’s config service, your config will live at https://admin.hlx.page/config/{{ORG}}/sites/{{SITE}}/public.json but can be overwritten with a local /config.json file in your code repo.

default values

By default, the values in the demo-config.json file are from the boilerplate’s sample backend to ensure everything works out of the box. But when it comes time to connect your own backend, you need to know what each key means so you can update it with the correct value from your own Commerce instance.

getConfigValue function

The getConfigValue function is a helper function that retrieves the value from the configs file using the dot-notation path as an argument. For example, getConfigValue('headers.cs.x-api-key') returns the value of [root config].headers.cs.x-api-key.

getHeaders function

The getHeaders function is a helper function which takes a storefront scope (like cs, cart, etc) and reads values from the configs file with the corresponding header keys and returns an object map of those rows. For example, if you have properties in config like headers.cs.Magento-Environment-Id": "abc-123", then getHeaders('cs') will return an object like { "Magento-Environment-Id": "abc-123"}.

Configuration Caching

The storefront configuration is cached at multiple levels to optimize performance:

  • CDN Caching: The configuration file is cached by the EDS CDN with a max-age=7200 (2 hours) cache control header. This means configuration changes can take up to 2 hours to be reflected on the CDN after deployment.

  • Browser Caching: When the configuration is loaded in the browser, it is stored in session storage, which persists until the browser session is cleared.

For developers: After making configuration changes, it can take up to two hours for the CDN cache to expire. Clear your browser’s session storage to see updates. Verify the current cache configuration by accessing <site.com>/config.json directly and checking the last-modified header.

Configuration Sections

The following sections detail each part of your configuration for Adobe Commerce. Each section includes placeholders (marked with {{PLACEHOLDER}}) that you must replace with your specific Commerce environment details.

You can find your configuration in your code repo at /config.json or /demo-config.json, or in the config service for your site. If you do not have a configuration yet, use the Config Generator tool to automatically generate the configuration for your backend.

Endpoints

The endpoints properties define the GraphQL API endpoints for your Commerce backend.

{
  "commerce-core-endpoint": "{{COMMERCE_CORE_ENDPOINT}}",
  "commerce-endpoint": "{{COMMERCE_ENDPOINT}}"
}

Configuration Properties:

  • commerce-core-endpoint (read/write) - Core GraphQL endpoint for queries and mutations. This endpoint handles all write operations and some read operations. See Adobe Commerce GraphQL API for details.

  • commerce-endpoint (read-only) - Services GraphQL endpoint optimized for read-only operations with Catalog Service, Live Search, and Product Recommendations. It is also optimized for performance for product data retrieval. For details, see the following documentation:

Headers

The headers section defines HTTP headers required for API authentication and store context. Headers are organized by scope to apply different authentication and context settings for different request types. The specific headers required depend on your Commerce environment type.

Adobe Commerce PaaS environments use standard Adboe Commerce header naming conventions and require API keys for SaaS services.

{
  "headers": {
    "all": {
      "Store": "{{STORE_VIEW_CODE}}"
    },
    "cs": {
      "Magento-Store-Code": "{{STORE_CODE}}",
      "Magento-Store-View-Code": "{{STORE_VIEW_CODE}}",
      "Magento-Website-Code": "{{WEBSITE_CODE}}",
      "x-api-key": "{{API_KEY}}",
      "Magento-Environment-Id": "{{ENVIRONMENT_ID}}"
    }
  }
}

Header Scopes:

  • all - Headers applied to all GraphQL requests

    • Store - Store view code for Core GraphQL requests. See GraphQL Headers for details.

  • cs - Headers for Catalog Service requests

    • Magento-Store-Code - Store to connect to. See Create stores for details.
    • Magento-Store-View-Code - Store view for Catalog Service requests. See Store views for details.
    • Magento-Website-Code - Website to connect to. See Create websites for details.
    • x-api-key - API key for SaaS services (Catalog Service, Live Search, Product Recommendations). See Commerce Services Connector for details.
    • Magento-Environment-Id - Connects the storefront to the cloud instance serving it. See Cloud Environment overview for details.

Analytics

The analytics section contains store and environment metadata for tracking and reporting. The specific values depend on your Commerce environment type.

For Adobe Commerce PaaS and Adobe Commerce as a Cloud Service environments, use standard Commerce store and website identifiers from your Commerce Environment. You can obtain these values using a storeConfig query.

{
  "analytics": {
    "base-currency-code": "{{CURRENCY_CODE}}",
    "environment": "{{ENVIRONMENT_TYPE}}",
    "environment-id": "{{ENVIRONMENT_ID}}",
    "store-code": "{{STORE_CODE}}",
    "store-id": {{STORE_ID}},
    "store-name": "{{STORE_NAME}}",
    "store-url": "{{STORE_URL}}",
    "store-view-code": "{{STORE_VIEW_CODE}}",
    "store-view-id": {{STORE_VIEW_ID}},
    "store-view-name": "{{STORE_VIEW_NAME}}",
    "website-code": "{{WEBSITE_CODE}}",
    "website-id": {{WEBSITE_ID}},
    "website-name": "{{WEBSITE_NAME}}"
  }
}

Configuration Properties:

  • base-currency-code - The base currency code for the store (e.g., “USD”, “EUR”)
  • environment - Environment type (“Production”, “Testing”)
  • environment-id - Unique identifier for the Commerce environment
  • store-url - Base URL for the store
  • store-code - Code identifier for the store from your Commerce environment
  • store-id - Numeric ID for the store
  • store-name - Display name for the store
  • store-view-code - Code identifier for the store view
  • store-view-id - Numeric ID for the store view
  • store-view-name - Display name for the store view
  • website-code - Code identifier for the website from your Commerce environment
  • website-id - Numeric ID for the website
  • website-name - Display name for the website

Plugins

The plugins section configures various Commerce plugins and features.

{
  "plugins": {
    "picker": {
      "rootCategory": "{{ROOT_CATEGORY_ID}}"
    }
  }
}

Configuration Properties:

  • picker.rootCategory - Root category ID for the product picker. This determines which category serves as the starting point when browsing products in the Commerce interface.

Multistore

The multistore section manages configurations for multiple store views and internationalization. This allows different configurations for different locales or store views. Each non-”default” configuration will be merged with the default at runtime and used for the corresponding locale or store view. For example, the below would serve as a basis for configuration for the site at aemshop.net/fr.

{
  "/fr/": {
    "headers": {
      "all": {
        "Store": "{{FRENCH_STORE_VIEW_CODE}}"
      },
      "cs": {
        "Magento-Store-Code": "{{FRENCH_STORE_CODE}}",
        "Magento-Website-Code": "{{FRENCH_WEBSITE_CODE}}",
        "Magento-Store-View-Code": "{{FRENCH_STORE_VIEW_CODE}}"
      }
    }
  }
}

Configuration Properties:

  • Path-based configuration - Use URL paths (like /fr/, /de/, etc.) to define locale-specific or store-specific overrides
  • Header overrides - Override default headers for specific store views
  • Store context - Define different store, website, and store view codes for each locale

Additional Configuration Options

Some configuration options can be set to enable or disable certain boilerplate features.

{
  "commerce-assets-enabled": boolean,
  "commerce-companies-enabled": boolean,
}
  • commerce-assets-enabled - Boolean flag to enable or disable AEM Assets within the storefront
  • commerce-companies-enabled - Boolean flag to enable or disable Commerce B2B features within the storefront

Configuration Examples

The following examples show real config.json files from different Adobe Commerce environments. These examples demonstrate the actual structure and values used in production environments.

This example shows the configuration for an Adobe Commerce PaaS environment, which includes additional features like multistore support and asset management. This configuration is used on this site: https://www.aemshop.net/

{
  "public": {
    "default": {
      "commerce-core-endpoint": "https://www.aemshop.net/graphql",
      "commerce-endpoint": "https://www.aemshop.net/cs-graphql",
      "headers": {
        "all": {
          "Store": "default"
        },
        "cs": {
          "Magento-Store-Code": "main_website_store",
          "Magento-Store-View-Code": "default",
          "Magento-Website-Code": "base",
          "x-api-key": "4dfa19c9fe6f4cccade55cc5b3da94f7",
          "Magento-Environment-Id": "f38a0de0-764b-41fa-bd2c-5bc2f3c7b39a"
        }
      },
      "analytics": {
        "base-currency-code": "USD",
        "environment": "Production",
        "environment-id": "f38a0de0-764b-41fa-bd2c-5bc2f3c7b39a",
        "store-code": "main_website_store",
        "store-id": 1,
        "store-name": "Main Website Store",
        "store-url": "https://www.aemshop.net",
        "store-view-code": "default",
        "store-view-id": 1,
        "store-view-name": "Default Store View",
        "website-code": "base",
        "website-id": 1,
        "website-name": "Main Website"
      },
      "plugins": {
        "picker": {
          "rootCategory": "2"
        }
      },
      "commerce-assets-enabled": false
    },
    "/fr/": {
      "headers": {
        "all": {
          "Store": "fr"
        },
        "cs": {
          "Magento-Store-Code": "fr_store",
          "Magento-Website-Code": "fr_website",
          "Magento-Store-View-Code": "fr"
        }
      }
    }
  }
}

Step-by-step

We’ll use a mock PDP / Catalog Service block to demonstrate how to utilize the config utilities and values. This example shows how to access the configuration sections detailed above.

Import the configuration functions.

First, import the getConfigValue and getHeaders functions from your boilerplate’s scripts/configs.js file.

import { getConfigValue, getHeaders } from '../../scripts/configs.js';

Access endpoint configuration.

Use the getConfigValue function to retrieve endpoint URLs from the configuration. This function takes a dot-notation path that matches the keys in your config.json.

export default async function decorate(block) {
  // Get the catalog service endpoint from the endpoints section
  const catalogEndpoint = await getConfigValue('commerce-endpoint');
  const coreEndpoint = await getConfigValue('commerce-core-endpoint');


  console.log('Catalog Service endpoint:', catalogEndpoint);
  console.log('Core Commerce endpoint:', coreEndpoint);
}

Access header configuration.

Use the getHeaders function to retrieve headers for specific scopes. This function automatically formats the headers for use in HTTP requests.

export default async function decorate(block) {
  // Get headers for Catalog Service requests
  const csHeaders = await getHeaders('cs');


  // Get headers for all requests
  const allHeaders = await getHeaders('all');


  console.log('CS headers:', csHeaders);
  console.log('All headers:', allHeaders);
}

Access analytics and other configuration.

Use getConfigValue to access any configuration value using dot notation, including analytics data and plugin settings.

export default async function decorate(block) {
  // Get analytics configuration
  const storeName = await getConfigValue('analytics.store-name');
  const currency = await getConfigValue('analytics.base-currency-code');


  // Get plugin configuration
  const rootCategory = await getConfigValue('plugins.picker.rootCategory');


  console.log('Store:', storeName, 'Currency:', currency);
  console.log('Root category:', rootCategory);
}

Make API requests with configuration.

Combine the endpoint and header configuration to make authenticated API requests to your Commerce backend.

export default async function decorate(block) {
  // Get the catalog service endpoint
  const endpoint = await getConfigValue('commerce-endpoint');


  // Get the catalog service required headers
  const headers = await getHeaders('cs');


  // Make the API request
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...headers
    },
    body: JSON.stringify({
      query: `query { products { items { name } } }`
    })
  });


  const data = await response.json();
  // Process the response data
}

Summary

The Commerce configuration provides a structured approach to connecting your storefront to Adobe Commerce backends. By organizing settings into clear sections for endpoints, headers, analytics, plugins, and multistore configurations, you can easily customize your storefront for different Commerce environments. The configuration system supports Adobe Commerce (PaaS), Adobe Commerce as a Cloud Service (ACCS), and Adobe Commerce Optimizer (ACO), each with specific header requirements and authentication methods. Use the getConfigValue and getHeaders helper functions to access these settings in your Commerce blocks, ensuring consistent and maintainable integration with your Commerce backend.