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.