Coveo JavaScript Search Framework

Common errors

• This DOM element has already been initialized as a search interface, skipping initialization

  cause Attempting to call `Coveo.init()` on a DOM element that has already been initialized, typically occurring when a search token expires and a re-initialization is attempted instead of renewal.
  fix Pass a function to the `accessToken` option of `Coveo.init()` that returns a promise resolving to a new token. The framework will call this function automatically when the token needs renewal. Do not call `Coveo.init()` multiple times on the same root element.

• Coveo is not defined

  cause The main Coveo JavaScript Search Framework script (CoveoJsSearch.min.js) has not been loaded or executed before attempting to access the `Coveo` global object. This can happen if script tags are in the wrong order, or if module imports are not correctly bundled.
  fix Ensure that `CoveoJsSearch.min.js` (or its lazy equivalent) is loaded via a `<script>` tag in your HTML *before* any inline scripts that use `Coveo`, or that your module bundler correctly includes `coveo-search-ui` and the `import * as Coveo from 'coveo-search-ui'` statement is at the top of your relevant module.

• SearchUIController: Initialization error Error in $A.getCallback() [Cannot assign to read only property 'removeEventListener' of object '[object Object]']

  cause Observed in Salesforce Lightning Communities on mobile, this error occurs when Salesforce's LockerService blocks an internal 'fastclicks' library used by `coveo-search-ui`.
  fix Upgrade to Coveo for Salesforce package version 3.31 or later, which includes a fix. As a workaround, add a custom script to override `Coveo.SearchInterface.prototype.setupMobileFastclick` to an empty function.

• The provided index '{0}' was not found. OR Exception System.NullReferenceException: Object reference not set to an instance of an object.

  cause These errors, often seen in Sitecore integrations with Coveo, usually indicate that the search indexes are not properly initialized or are unavailable, potentially due to Sitecore instance startup/shutdown or incorrect installation/configuration of Coveo for Sitecore.
  fix Review Sitecore logs for specific initialization failures or `NullReferenceException` details. Ensure all Coveo for Sitecore components are correctly installed, configured, and that indexes are initialized and accessible. Rebuilding indexes may resolve the issue.

Warnings

• deprecated The `coveo-search-ui` package is in maintenance mode. For new projects, Coveo strongly recommends using the modern, framework-agnostic Atomic or Headless libraries, which offer greater flexibility and performance.
  Fix: For new implementations, evaluate `@coveo/atomic` or `@coveo/headless`. For existing projects, be aware that new features are unlikely to be added, and focus will be on bug fixes and critical updates.
• breaking Upgrading from version 1.x to 2.x introduced several breaking changes, including the removal of internal jQuery dependencies and updates to component initialization. While generally straightforward, careful review of upgrade guidelines is essential.
  Fix: Consult the official 'Version 1.x to 2.x breaking changes and upgrade guidelines' documentation. Thoroughly test existing custom components and integrations after upgrading.
• gotcha Search tokens used for authentication can expire. If not handled, this leads to an error 'This DOM element has already been initialized as a search interface, skipping initialization' because the framework cannot re-initialize with a new token directly.
  Fix: Configure the `accessToken` option in `Coveo.init()` to accept a function that asynchronously fetches and returns a fresh search token when needed. This allows the framework to automatically renew the token.
• breaking The `DynamicFacet` and `DynamicHierarchicalFacet` components now have `filterFacetCount` parameter set to `true` by default since a 2021 release, which changes how facet search requests are sent.
  Fix: Review `DynamicFacet` and `DynamicHierarchicalFacet` implementations. If previous behavior (where `filterFacetCount` was `false` by default) is desired, explicitly set `data-filter-facet-count='false'` on the component's HTML element.
• breaking Changes to Usage Analytics event logging occurred. Specifically, the `notifications` trigger changed from a string to a string array, and `customData.executed` was replaced by `customData.executions` (an array of objects). This affects how analytics reports are structured.
  Fix: Adjust any custom Usage Analytics reports or integrations that rely on the `notifications` trigger or `customData.executed` to reflect the new `executions` array format.

Install

• npm install coveo-search-ui npm
• yarn add coveo-search-ui yarn
• pnpm add coveo-search-ui pnpm

Imports

• Coveo
  wrong:

  const Coveo = require('coveo-search-ui');

  correct:

  import * as Coveo from 'coveo-search-ui';

  For module bundlers, `import * as Coveo` makes the global Coveo object available. Direct `require` might not expose all global members correctly without further assignment or specific configuration.
• ISearchInterfaceOptions

  import { ISearchInterfaceOptions } from 'coveo-search-ui';

  Type definitions like ISearchInterfaceOptions are available for use in TypeScript for stricter component configuration.
• Searchbox Component (via HTML)
  wrong:

  import { Searchbox } from 'coveo-search-ui';

  correct:

  <div class="CoveoSearchbox" data-options='{}'></div>

  Individual UI components in the classic framework are primarily declared via specific HTML class names and `data-` attributes, then initialized by `Coveo.init()`, rather than imported directly as classes or functions in JavaScript modules.

Quickstart

This quickstart demonstrates the foundational setup of a Coveo search interface using `coveo-search-ui`. It includes configuring the cloud endpoint with an API key and organization ID, defining essential search components via HTML classes, and initializing the framework.

import * as Coveo from 'coveo-search-ui';

// Ensure Coveo CSS is loaded (example for Webpack/bundlers)
// import 'coveo-search-ui/bin/css/CoveoFullSearch.min.css';

// Basic HTML structure for the search interface
// This would typically be in an HTML file or injected into the DOM.
const appRoot = document.getElementById('search-root') || document.createElement('div');
appRoot.id = 'search-root';
document.body.appendChild(appRoot);

appRoot.innerHTML = `
  <div class="CoveoSearchInterface" id="search">
    <div class="CoveoSearchbox"></div>
    <div class="CoveoResultList"></div>
    <div class="CoveoPager"></div>
  </div>
`;

const organizationId = process.env.COVEO_ORGANIZATION_ID ?? 'YOUR_ORG_ID';
const accessToken = process.env.COVEO_ACCESS_TOKEN ?? 'YOUR_API_KEY'; // Ensure this key has 'Search - Execute queries' privilege
const searchHub = process.env.COVEO_SEARCH_HUB ?? 'default';

(async () => {
  // Configure the search endpoint
  Coveo.SearchEndpoint.configureCloudEndpoint(
    organizationId,
    accessToken,
    searchHub
  );

  // Initialize the framework on the root element of the search interface
  // For token renewal, pass a function that returns a new token.
  Coveo.init(document.getElementById('search') as HTMLElement, {
    // Additional options can be passed here
    // For example, to handle token renewal:
    // accessToken: () => fetch('/api/renew-token').then(res => res.text())
  });

  console.log('Coveo Search Interface initialized.');
})();