Skip to content

Search is only available in production builds. Try building and previewing the site to test it out locally.

Product Discovery installation

This guide will help you install and configure the Product Discovery drop-in component in your storefront.

Prerequisites

Before you begin, ensure you have:

  • Adobe Commerce instance with Live Search enabled
  • Access to your store’s GraphQL endpoint
  • Required API keys and credentials
  • Node.js and npm installed on your development environment

Step-by-step

Use the following steps to install the Product Discovery drop-in component:

Install the packages

Use a CDN or NPM (recommended for performance) to install the drop-in component tools (@dropins/tools) and product discovery (@dropins/storefront-product-discovery) packages.

npm install @dropins/tools @dropins/storefront-product-discovery

Map the packages

In the <head> tag of your index.html or head.html file, use an importmap pointed to the node_modules directory, a custom local directory, or CDN (for run-time environments).

This example shows an importmap added to a head.html The importmap points both packages to the local node_modules directory that contains your installed drop-in component files from the drop-in component tools (@dropins/tools) and the product discovery (@dropins/storefront-product-discovery):

head.html
<script type="importmap">
{
"imports": {
"@dropins/tools/": "/node_modules/@dropins/tools/",
"@dropins/storefront-product-discovery/": "/node_modules/@dropins/storefront-product-discovery/",
}
}
</script>
<script src="/scripts/scripts.js" type="module"></script>

With the importmap defined for both runtime and build-time environments, you can now import the required files from these packages into your product list page block as described in the next step.

Initalize the drop-in

The code below shows how to register the product discovery component, configure place holders and translation files, as well as configuring GraphQL endpoint and header settings. You can add these functions as a script to your website and import the script on blocks where product discovery components are rendered.

product-dicovery-initializer.js
import { initializers } from '@dropins/tools/initializer.js';
import { initialize, setFetchGraphQlHeaders, setEndpoint } from '@dropins/storefront-product-discovery/api.js';
import { getHeaders } from '@dropins/tools/lib/aem/configs.js';
import { initializeDropin } from './index.js';
import { fetchPlaceholders, commerceEndpointWithQueryParams } from '../commerce.js';
await initializeDropin(async () => {
setEndpoint(await commerceEndpointWithQueryParams());
setFetchGraphQlHeaders((prev) => ({ ...prev, ...getHeaders('cs') }));
const labels = await fetchPlaceholders('placeholders/search.json');
const langDefinitions = {
default: {
...labels,
},
};
return initializers.mountImmediately(initialize, { langDefinitions });
})();

Import the required files

Import the required files from the drop-in components tools (@dropins/tools/fetch-graphql.js', @dropin/tools/initializers.js), the product discovery drop-in (@dropins/storefront-product-discovery), and the initialzer file created in previous step into a JavaScript file for your product list page block, and header block. The example here shows the imports added to a product-list-page.js file and to a header.js file. These imports constitute the minimum imports you need to create a fully functioning product discovery for your site:

product-list-page.js
// component tools
import { initializers } from '@dropins/tools/initializer.js';
import { events } from '@dropins/tools/event-bus.js';
// drop-in component functions
import * as pkg from '@dropins/storefront-product-discovery/api.js';
// Drop-in component provider
import { render as provider } from '@dropins/storefront-product-discovery/render.js';
// Drop-in component containers
import ProductList from '@dropins/storefront-product-discovery/containers/ProductList.js';
import Facets from '@dropins/storefront-product-discovery/containers/Facets.js';
import ResultsInfo from '@dropins/storefront-product-discovery/containers/ResultsInfo.js';
// Initializers
import '../../scripts/initializers/product-discovery-initializer.js';

Configure and render the product discovery drop-in components

Render the product dicovery drop-in components on the page. The example below shows how to render the product discovery drop-in components in a product-list-page.js file. The example also shows how to render the search bar in a header.js file.

product-list-page.js
// Create a fragment to hold the product discovery drop-in components
const fragment = document.createRange().createContextualFragment(`
<div class="search__input"></div>
<div class="search__wrapper">
<div class="search__left-column">
<div class="search__result-info"></div>
<div class="search__facets"></div>
</div>
<div class="search__right-column">
<div class="search__product-list"></div>
</div>
</div>
`);
const $resultInfo = fragment.querySelector('.search__result-info');
const $facets = fragment.querySelector('.search__facets');
const $productList = fragment.querySelector('.search__product-list');
// Render the product discovery drop-in components
provider.render(ResultsInfo, { })($resultInfo);
provider.render(Facets, { })($facets);
provider.render(ProductList, { })($productList);
block.appendChild(fragment);

The Commerce boilerplate template includes all of the necessary drop-in components and configurations to help you get started quickly, so Adobe recommends relying on the boilerplate instead of installing, configuring, and integrating the drop-in components individually.