Search Engine
Integration with Coveo involves using the Headless library, which allows developers to utilize the native Coveo library for creating customized search experiences.
The factory producing search engine configuration is stored in the engine/engine-config.ts file. This file is used to initialize the search engine configuration. It is shared across the server-side rendering (SSR) and client engines.
Please, check the Coveo Headless documentation for more information about the library and its capabilities.
Request Preprocessor
All options are defined arbitrarily and can be adjusted to fit your specific needs. However, there is a specific withAlokai function that is necessary for the integration to work properly. It allows you to benefit from the middleware layer provided by the Alokai architecture.
This function routes the request to the middleware layer, where the request is processed and then sent to the Coveo API. The middleware layer normalizes the request and response data and handles communication with the Coveo API.
In most cases, you will not need to modify any parameters in the withAlokai function. However, you can do so if necessary. One common example is the whitelistedMethods parameter, which defines the methods that will be routed to the middleware layer. By default, the withAlokai function is set to handle the querySuggest, search, and productRecommendations methods, as these methods are expected to work with potentially heavy data that should be handled by the middleware layer. On the other hand, all analytics methods are not handled by the middleware layer and are sent directly to the Coveo API.
Removing the withAlokai function from the engine-config.ts file will cause
the Coveo integration to not work properly. The response will not be
normalized, and the data will not be aggregated properly in the middleware
layer.
Scope results to your catalog (search hub + query pipeline)
A Coveo organization can hold more than one source — for example separate pushes for different stores, catalogs, or environments. By default the storefront queries the organization's default query pipeline, which returns documents from every source. The result: your listing shows products that don't exist in the commerce backend this storefront is connected to, and opening one fails with a product not found error, because its code isn't in your catalog.
To avoid this, scope the storefront's queries to the single source that matches your backend, using a search hub and a query pipeline filter.
Pick a search hub
Set a search hub in your storefront environment. The engine sends it on every query (see search.searchHub in engine-config.ts), and Coveo uses it to select the matching query pipeline.
NEXT_PUBLIC_COVEO_SEARCH_HUB=hub-<your-store>NEXT_PUBLIC_* variables are inlined when the storefront starts — restart the dev server after changing them. An empty search hub falls back to the default pipeline, which applies no source scope.
Filter the pipeline to your source
In the Coveo Admin Console, create a query pipeline conditioned on that search hub (Search Hub is hub-<your-store>), then add a filter rule that keeps only your source:
@source==<your-source-name>Every query on that hub now returns documents from a single source, so listing results and the products your commerce backend can resolve stay in sync.
Verify with a quick search: the total result count should match your catalog
size, and opening any product should load its details without a product not found error.
Define facets
Headless library comes with defineFacets method that allows you to define facets for the search interface. However, this have a drawback that you need to define each facet manually, remember their names and use these keys in the code later. To overcome this, our facetManager has a method defineFacets that allows you to register all facets at once based on a single configuration file. This way, we use the same configuration in all places and we don't need to remember facet names or how to use them. We do it for you!
If you want to learn more about configuring facets, please check the Facet Configuration section.