Storefront configuration
In this section, you’ll learn how Commerce blocks in your storefront connect to a Commerce backend using values from the configs, configs-stage or configs-dev spreadsheets in the root of your SharePoint content directory.
In the Create your storefront tutorial, the sample content archive provided you with several configs spreadsheet files in the root folder. These files are one way in which authors can provide values to frontend blocks. Notably, the three files correspond to the different EDS environments. configs is used by aem.live, and represents production. configs-stage is used by aem.page and represents staging. configs-dev is used on localhost when you are running your EDS storefront locally.
You can forcibly change which config is fetched and used on your page by setting environment in SessionStorage to either dev, stage, or prod.
When implementing your own project, you must update the configuration values with:
The Catalog Service header values specific to your Adobe Commerce backend.
The Adobe Commerce and Catalog Service GraphQL endpoints that you configured as part of the content delivery network (CDN) setup.
Other values which are utilized by the Storefront codebase like
commerce-environment,commerce-base-currency-codeetc.
Vocabulary
Storefront configuration
The configs, configs-stage and configs-dev spreadsheets contain the connection settings for your Commerce blocks. Each row in the sheet contains a key and a value that corresponds to a specific setting or usage in your Commerce backend or in the Storefront codebase. The key is used to retrieve the value from the configs spreadsheet and is used to connect your Commerce blocks to your Commerce backend.
default values
By default, the values in the configs spreadsheet 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 key as an argument. The getConfigValue function is used to connect your Commerce blocks to your Commerce backend.
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 rows in config like "commerce.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 configs file in your content drive by clicking on the mountpoint link in your project’s fstab.yaml file. You should see the configs 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:
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-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.headers.cs.Magento-Environment-Id: Connects the storefront to the cloud instance that serves it. See Cloud Environment overview for details.
commerce.headers.cs.Magento-Website-Code: Determines the website to connect to. See Step 2: Create websites for details.
commerce.headers.cs.Magento-Store-Code: Determines the store to connect to. See Step 3: Create stores for details.
commerce.headers.cs.Magento-Store-View-Code: Determines the store view to connect to. See Step 4: Create store views and Store views for details.
commerce.headers.cs.Magento-Customer-group: Determines product discounts and tax classes. See Customer groups and the Create Customer Groups video for details.
commerce.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.