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.

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

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

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 that automates the site creation process, the config.json file is created for you in 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 either 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.

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 config 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"}.

Examples

You can find the configuration file in your code repo at either /config.json or /demo-config.json. The file provides a template with the keys and values to configure the connection to the Commerce backend.

The required configuration depends on the type of Commerce application that you are connecting to. Select the tabs below to review the available templates.

This boilerplate config.json for Adobe Commerce requires correct values for your Commerce environment.

{
  "public": {
    "default": {
      "commerce-core-endpoint": "https://www.aemshop.net/graphql",
      "commerce-endpoint": "https://www.aemshop.net/cs-graphql",
      "headers": {
        "all": {
          "Store": "{{YOUR_STOREVIEW_CODE}}"
        },
        "cs": {
          "Magento-Customer-Group": "b6589fc6ab0dc82cf12099d1c2d40ab994e8410c",
          "Magento-Store-Code": "{{YOUR_STORE_CODE}}",
          "Magento-Store-View-Code": "{{YOUR_STOREVIEW_CODE}}",
          "Magento-Website-Code": "{{YOUR_WEBSITE_CODE}}",
          "x-api-key": "{{YOUR_API_KEY}}",
          "Magento-Environment-Id": "{{YOUR_ENVIRONMENT_ID}}"
        }
      },
      "analytics": {
13 collapsed lines
        "base-currency-code": "USD",
        "environment": "Production",
        "store-id": 1,
        "store-name": "Main Website Store",
        "store-url": "{{YOUR_STORE_URL}}",
        "store-view-id": 1,
        "store-view-name": "Default Store View",
        "website-id": 1,
        "website-name": "Main Website"
      }
    }
  }
}

Each key is described below with links to more details. The value for each key is specific to your Commerce instance and can be provided by your Commerce administrator.

  1. commerce-core-endpoint: (read/write) Core GraphQL endpoint for queries and mutations. See Adobe Commerce GraphQL API for details.

  2. commerce-endpoint: (read-only) Services GraphQL endpoint for Catalog Service, Live Search, and Product Recommendations. See Catalog Service for details.

  3. headers.all.Store: Store view code for Core GraphQL requests. See GraphQL Headers for details.

  4. headers.cs.Magento-Customer-Group: Customer group for pricing and tax calculations. See Customer groups and the Create Customer Groups video for details. This should be the default value, but may need to be updated dynamically at runtime, such as after a user logs in.

  5. headers.cs.Magento-Store-Code: Determines the store to connect to. See Step 3: Create stores for details.

  6. headers.cs.Magento-Store-View-Code: Determines the store view to connect to, for Catalog Service requests. See Step 4: Create store views and Store views for details.

  7. headers.cs.Magento-Website-Code: Determines the website to connect to. See Step 2: Create websites for details.

  8. headers.cs.x-api-key: API key to access SaaS services (Catalog Service, Live Search, Product Recommendations). See Commerce Services Connector for details.

  9. headers.cs.Magento-Environment-Id: Connects the storefront to the cloud instance that serves it. See Cloud Environment overview for details.

All of the initializer blocks now automatically use any headers for the corresponding block if they are in the config. For example commerce.headers.cart.Foo will add a Foo header to graphql requests made by the cart dropin. This can be useful if you need to append certain headers for specific requests.

Step-by-step

We’ll use a mock PDP / Catalog Service block as an example of where and how to utilize the various config utilities and values.

Import the getConfigValue function.

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

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

Fetch and use some values.

Within the block’s decorate function, use the getConfigValue function which takes a string that matches one of the keys from the configs file and returns the corresponding value.

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');


  const response = await fetch(endpoint, { headers });


  // do stuff with response
}

Summary

That’s all it takes to connect a drop-in component Commerce block to your Commerce backend settings. You’ll use the same configuration keys to connect any custom Commerce blocks or new Commerce blocks provided in later releases.