Connecting to Headless Salesforce Commerce Cloud Using Official Boilerplate

By nature, headless architectures allow for more agility and flexibility. Therefore, various, very different approaches are labeled “headless.” This guide describes how the Algolia Salesforce Commerce Cloud (SFCC) Integration can fit in headless architecture and support its intended flexibility.

There are multiples ways to spin up a headless architecture with Salesforce Commerce Cloud B2C. There are three main steps to integrating Algolia with SFCC Headless:

1. Install the Algolia Link Integration.
2. Index your catalogs to Algolia.
3. Connect to a headless storefront.

In this guide, you’ll connect Algolia to a headless SFCC storefront using the official SFCC boilerplate. If you prefer to build a custom React front end instead of using the SFCC boilerplate, please refer to the guide on connecting a headless Salesforce Commerce Cloud using a React front end. Regardless of which method you use, the first two steps (installing the Algolia link Integration and indexing your catalogs to Algolia) are the same.

Install the Algolia Link Integration.

The Algolia Link is composed of four cartridges that work together to fit in various uses cases.

Unlike SiteGenesis or SFRA architectures, headless architectures only use the “server-side” cartridges, namely: int_algolia and bm_algolia.

To complete the installation, please follow the instructions in Set Up the Algolia Cartridge.

Index your catalogs

To index your catalogs, please follow the instructions in Index Your Catalogs to Algolia .

After successfully running the indexing jobs, navigate to the Indices section of the Algolia dashboard to ensure your catalogs are properly indexed.

Connect to a headless storefront

You can connect Algolia to Salesforce Commerce Cloud Headless using the official boilerplate in three steps:

1. Download and run the boilerplate.
2. Download and compile Unified UI.
3. Import Unified UI inside the boilerplate.

See details below.

Download and run the official headless boilerplate

In this section, we use the official boilerplate published by Salesforce: SalesforceCommerceCloud/sfcc-sample-apps. Later, we outline how to add Algolia to the boilerplate.

First, you need to download and run it using the following steps:

1. Clone the boilerplate repository: git clone --depth=1 https://github.com/SalesforceCommerceCloud/sfcc-sample-apps

2. Follow the setup instructions in the README.md until you have a running front-end application, running the native Commerce Cloud Search.

The next steps replaces the current native search with Algolia search.

Download and compile Unified UI

1. Clone the Unified UI package into the packages/ directory.

2. Delete the unified-instantsearch-ecommerce/.git file from the unified-instantsearch-ecommerce directory.

   Shell

   Copy

   1
   2
   3
    cd sfcc-sample-apps/packages
    git clone --depth=1 https://github.com/tkrugg/unified-instantsearch-ecommerce
    rm -rf unified-instantsearch-ecommerce/.git
   

3. Install dependencies and compile.

   Shell

   Copy

   1
   2
   3
   cd sfcc-sample-apps/packages/unified-instantsearch-ecommerce
   npm install
   npm run export
   

This creates a new folder unified-instantsearch-ecommerce/export which contains the assets you need to have a working search in the boilerplate.

Import Unified UI into the boilerplate

The last step is to import the Unified UI assets into your boilerplate.

1. Add Unified UI assets to be copied into the storefront-lwc package.

   To do so, change the file packages/storefront-lwc/scripts/plugin-copy-assets.js in the following way:

   JavaScript

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
    /* inside packages/storefront-lwc/scripts/plugin-copy-assets.js */
   
    const ASSETS = {
        'src/assets/favicon.ico': 'favicon.ico',
        'src/assets/manifest.json': 'manifest.json',
        'src/assets/fonts/': 'fonts/',
        'src/assets/images/': 'images/',
        'src/assets/img/': 'img/',
   +    '../unified-instantsearch-ecommerce/export/': 'algolia_unified_ui/',
    };
   

   Now, building storefront-lwc automatically imports Unified UI files.

2. Reference the newly added files inside the index.html file:

   HTML

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
       <!-- inside packages/storefront-lwc/src/index.html -->
   
       <link rel="manifest" href="/manifest.json" />
       <link rel="shortcut icon" href="/favicon.ico" />
       <link rel="stylesheet" href="/css/global.css" />
   
   +   <link rel="stylesheet" href="/algolia_unified_ui/search.css" />
   +   <script src="/algolia_unified_ui/search.js"></script>
   

3. Create a new Lightning Element that will serve as a host for Algolia Unified UI.

   3.1. Within the packages/storefront-lwc/src/modules/ folder, create a new folder called algoliaUnifiedUi, and algoliaUnifiedUi.html and algoliaUnifiedUi.js files within that folder.

   Shell

   Copy

   1
   2
    mkdir -p packages/storefront-lwc/src/modules/algoliaUnifiedUi
    touch packages/storefront-lwc/src/modules/algoliaUnifiedUi/algoliaUnifiedUi.{html,js,scss}
   

   3.2. Fill in algoliaUnifiedUi.html and algoliaUnifiedUi.js with the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
export default class AlgoliaUnifiedUi extends LightningElement {
   renderedCallback() {
       const productsIndexName = 'zzgk_001_sandbox_us01_dx__RefArch__products__en_US'; // Check to ensure this matches your products index's name
       const currencyCode = 'EUR';

       window.UnifiedUI.start({
           inputContainer: this.template.querySelector('.site-search'),
           keyboardShortcuts: false,
           appId: '<Your Algolia application ID>',
           searchApiKey: '<Your Algolia Search-only API Key>',
           currencyCode,
           index: {
               indexName: productsIndexName,
               searchParameters: {
                   analytics: true,
                   clickAnalytics: true,
                   hitsPerPage: 18,
                   attributesToSnippet: ['short_description:25'],
               },
           },
           sorts: [
               {
                   label: 'Price ascending',
                   value: `${productsIndexName}__price_${currencyCode}_asc`,
               },
               {
                   label: 'Price descending',
                   value: `${productsIndexName}__price_${currencyCode}_desc`,
               },
           ]
       });
  }
}

1
2
3
<template>
    <div class="site-search"></div>
</template>

Once you’ve completed these steps, you will have integrated Algolia Unified UI into the front-end boilerplate for headless storefronts and should have a complete search implementation in place.