Setup

Storefront configuration

In this section, you’ll learn how Commerce blocks in your storefront connect to a Commerce backend using values from the configs.xlsx in the root of your SharePoint content directory.

In the Create your storefront tutorial, the sample content archive provided you with a configs.xlsx file in the root folder. This file is used to expose Adobe Commerce configuration parameters to the frontend blocks.

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

The Catalog Service header values specific to your Adobe Commerce backend.
The configuration values with the core Adobe Commerce GraphQL endpoint that you configured as part of the content delivery network (CDN) setup.

Vocabulary

Storefront configuration

The configs.xlsx file contains the connection settings for your Commerce blocks. Each row in the file contains a key and a value that corresponds to a specific setting in your Commerce backend. The key is used to retrieve the value from the configs.xlsx file and is used to connect your Commerce blocks to your Commerce backend.

default values

By default, the values in the configs.xlsx 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.xlsx file using the key as an argument. The getConfigValue function is used to connect your Commerce blocks to your Commerce backend.

Commerce block connection

To connect a Commerce block to your Commerce backend, you’ll use the getConfigValue function to set the Services endpoint and GraphQL headers for the block. The Services endpoint is the URL for the block’s GraphQL endpoint, and the GraphQL headers are the headers required to make a request to the endpoint.

Examples

You can find the configs.xlsx file in your content drive by clicking on the mountpoint link in your project’s fstab.yaml file. You should see the configs.xlsx file at the root of the SharePoint directory. Open the file to view the connection keys and values of the sample backend. They should look similar (but not exact) to the following:

#	Key	Value
1	commerce-endpoint	https://catalog-service-sandbox.adobe.io/graphql
2	commerce-core-endpoint	https://mystorefront.com/graphql
3	commerce-environment-id	7cb935fd-d3bc-487b-9a2f-e5965c30f2a1
4	commerce-root-category-id	2
5	commerce-website-code	base
6	commerce-store-code	main_website_store
7	commerce-store-view-code	default
8	commerce-customer-group	d0b8ea36fca097dc92c02b1d104e6f41099184cb
9	commerce-x-api-key	a6b4e2f69a4a4267a8f423c8caaf6a47

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.
commerce-environment-id: Connects the storefront to the cloud instance that serves it. See Cloud Environment overview for details.
commerce-root-category-id: Determines the products in the storefront’s main menu. See Step 1: Create root categories, Catagories overview, and Root category and hierarchy for details.
commerce-website-code: Determines the website to connect to. See Step 2: Create websites for details.
commerce-store-code: Determines the store to connect to. See Step 3: Create stores for details.
commerce-store-view-code: Determines the store view to connect to. See Step 4: Create store views and Store views for details.
commerce-customer-group: Determines product discounts and tax classes. See Customer groups and the Create Customer Groups video for details.
commerce-x-api-key: Provides access to SaaS storefront services (Catalog Service, Live Search, and Product Recommendations). See Commerce Services Connector for details.

Step-by-step

We’ll use the product-details Commerce block as an example of where and how to updated the connection settings for your Commerce blocks when switching to your own Commerce backend.

Import the getConfigValue function.

First, import the getConfigValue function from your boilerplate’s scripts/configs.js file. The getConfigValue function takes a string that matches one of the keys from the configs.xlsx file and returns the corresponding value.

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

Set the endpoint and fetch headers.

Within the Commerce block’s decorate function, use the getConfigValue function to set the Services endpoint and GraphQL headers for the dropin block.

export default async function decorate(block) {
  // Initialize Drop-ins
  initializers.register(product.initialize, {});

  // Set Fetch Endpoint (Service)
  product.setEndpoint(await getConfigValue('commerce-endpoint'));

  // Set Fetch Headers (Service)
  product.setFetchGraphQlHeaders({
    'Content-Type': 'application/json',
    'Magento-Environment-Id': await getConfigValue('commerce-environment-id'),
    'Magento-Website-Code': await getConfigValue('commerce-website-code'),
    'Magento-Store-View-Code': await getConfigValue('commerce-store-view-code'),
    'Magento-Store-Code': await getConfigValue('commerce-store-code'),
    'Magento-Customer-Group': await getConfigValue('commerce-customer-group'),
    'x-api-key': await getConfigValue('commerce-x-api-key'),
  });

  //more...
}

Summary

That’s all it takes to connect a dropin 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.