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.

In the Create your storefront tutorial, the template repo provided you a demo-config.json file in the root folder. This file contains the environment values for a Commerce backend including GraphQl endpoints and headers.

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.

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 config file in your code repo at either /config.json or /demo-config.json. You can view the sample backend’s connection keys and values in the file. They should look similar to this:

{
  "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": {
        "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.

commerce-endpoint: (read-only) Services GraphQL endpoint optimized for Catalog Service, Live Search, and Product Recommendations. See Catalog Service for details.
commerce-core-endpoint: (read/write) Core GraphQL endpoint for a variety of queries and mutations. See Adobe Commerce GraphQL API for details.
headers.all.Store: Determines the store view to connect to, for Core requests. See Core GraphQL Headers documentation for details.
headers.cs.Magento-Environment-Id: Connects the storefront to the cloud instance that serves it. See Cloud Environment overview for details.
headers.cs.Magento-Website-Code: Determines the website to connect to. See Step 2: Create websites for details.
headers.cs.Magento-Store-Code: Determines the store to connect to. See Step 3: Create stores for details.
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.
headers.cs.Magento-Customer-group: Determines product discounts and tax classes. See Customer groups and the Create Customer Groups video for details.
headers.cs.x-api-key: Provides access to SaaS storefront services (Catalog Service, Live Search, and Product Recommendations). See Commerce Services Connector 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.