How To Get Started With A Coveo Headless Project

Well, according to Coveo, it's "a library for developing Coveo-powered UI components." Don't confuse this with the Coveo JSUI or Coveo Turbo. If you develop with React or VueJs as an example, this will be right up your alley.

While Headless is in its early stages and still largely in development, it's still very much a functioning platform for delivering the Coveo experience to your users. If you're looking to add a search experience to your website, JSUI might be more what you're after. This is really the platform for integrating Coveo within either an application, whether it be mobile, desktop, or something that's just all self contained.

You can read more about Coveo Headless https://docs.coveo.com/en/headless. Currently they're at v0.1.0 but development is advancing quickly with additional features and functionality always being added.

Getting Your Environment Ready

Before you can even begin playing around with Coveo Headless, however, you're going to want to get a proper environment setup first. This includes installing:

• Node JS
• Python
• React
• Typescript
• etc...

Seems monumental, but it's really not. There's a very straight-forward set of tasks you need to follow in order to get your system setup and ready to build on.

Node JS

First thing first, head over to https://www.nodejs.org and download the latest version of NodeJS. You'll want 12+ in order to use and incorporate the functionality required.

My suggestion would be to when prompted during the install, is to include all the extras. This won't be the first project, nor the last, that requires .Net compilers, Python, etc., and if you don't already have those from previous installs, you'll need them here. While you don't actually code in .Net or Python, some of the node modules utilize them. It can take up a fair bit of time to install and a chunk of hard drive space but will save you pain in the long run.

If you're trying to juggle multiple Node versions, be sure to check out NVM and NPX for Multiple Environments.

Create A Project

Somewhere you're comfortable with, create a project directory. Now there are several ways to go from here on out.

We can create an empty project, initialize it, update the package.json file with what's needed and continue on from there. If you're wanting to learn each step of how Headless runs, I would suggest this approach but it's going to take you longer to get something up and running. It's also more prone to errors.

Or, we can download the latest from their sandbox repository and start ahead. The ramp up will be faster, but you'll want to take time to see all the inner-workings, some of which I hope to cover here.

While creating a project from scratch is good practice, we're going to save some time and download the project as-is. Once you have it downloaded, let's take a look at what's all there. Open up the contents in your favorite text editor; we like Visual Studio Code as you can quickly jump back and forth between each of the files. Keep in mind; this structure is a point-in-time version. It's possible, given Headless is still in development, your structure won't resemble this one 100%.

There's a lot here and while we're not going to cover EVERYTHING today, I want to focus on the important files first.

package.json

This is where all the required tools are defined and version to version of Coveo Headless small incremental changes are made here, so if you're ever experiencing issues after updating be sure to review.

        {
            "name": "coveo-headless-react-tsx-material-ui-example-010",
            "version": "1.0.0",
            "description": "",
            "keywords": [],
            "main": "src/index.tsx",
            "dependencies": {
              "@coveo/headless": "0.1.0",
              "@material-ui/core": "4.11.0",
              "@material-ui/icons": "4.11.2",
              "@material-ui/lab": "4.0.0-alpha.56",
              "cross-fetch": "3.0.5",
              "react": "^16.12.0",
              "react-dom": "^16.12.0",
              "react-scripts": "3.3.0"
            },
            "devDependencies": {
              "@types/react": "16.9.19",
              "@types/react-dom": "16.9.5",
              "typescript": "3.7.5"
            },
            "scripts": {
              "start": "react-scripts start",
              "build": "react-scripts build",
              "test": "react-scripts test --env=jsdom",
              "eject": "react-scripts eject"
            },
            "browserslist": [
              ">0.2%",
              "not dead",
              "not ie <= 11",="" "not="" op_mini="" all"="" ]="" }="">

tsconfig.json

The tsconfig.json file is needed because we're using TypeScript (ts/tsx) and not JavaScript/JSX.

        {
            "include": [
                "./src/*"
            ],
            "compilerOptions": {
                "strict": true,
                "esModuleInterop": true,
                "lib": [
                    "dom",
                    "es2015"
                ],
                "jsx": "react"
            }
        }
    

Install Node Modules

Now that we have the project unpacked in your directory; via the Command Prompt, you'll want to run the following to install all the dependent modules:

npm install
    

This will install the necessary items needed to be able to run the project. Because this is in early development, you may encounter errors. Coveo Headless itself can be installed directly if you wanted to install things bit by bit, via the following:

npm install @coveo/headless
    

Start The Project

To see that you are successful, start the project using the following command:

npm start
    

If it works, you should see something similar to what what you saw on their sandbox above.

If you're not seeing that but instead seeing error messages during the startup procedure, we've included a few of the common errors we've encountered that may help. If you did see what's presented above, you'll see that it's currently using the default sample configuration.

Let's Customize It

Now that we have it running, so begins the fun part of customizing it to meet our needs. First, I'd suggest hooking it up to your organization and relevant sources.

Customize The Endpoint

The Engine.tsx file is where Coveo Headless is configured and where it's pointing. So if we want to point it to a new organization, this is where we'd do it. The code itself should resemble what you've perhaps seen when using JSUI.

In order to point Coveo to our organization, you can update that file to resemble the following:

import { HeadlessEngine, searchPageReducers } from "@coveo/headless";

export const headlessEngine = new HeadlessEngine({
  configuration: {
    organizationId: "ORG NAME GOES HERE",
    accessToken: "API ACCESS TOKEN GOES HERE"
  },
  reducers: searchPageReducers
});
    

Update The Query Pipeline

Pointing to our organization is one thing; using a configured Query Pipeline is another. So let's do that. Open up App.tsx

Within the default class, you'll want to update it prior to SearchActions.executeSearch, as at that point the first query is made. Insert the following to point it to the default Query Pipeline.

let searchConfig = {pipeline:'default',searchHub:''};
dispatch(ConfigurationActions.updateSearchConfiguration(searchConfig));
    

At this point, whatever sources, or filters you have running in that query pipeline, the results should reflect that.

It Didn't Start; What Next?

So something failed, but it's not immediately clear what. I've captured a few of the common errors encountered and hope to show what may be causing them and what might be a solution.

TypeError [ERR_INVALID_ARG_TYPE]

When running the project, via the following, you may get the odd error message:

    TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined
        at new NodeError (node:internal/errors:329:5)
        at validateString (node:internal/validators:129:11)
        at Object.join (node:path:397:7)
        at noopServiceWorkerMiddleware 
    

If you received this, there's a good chance that when running npm install that it failed or didn't finish. Have a look, even run it again. If it is still failing, then there's a good chance that one or more of the packages that are needed are not installed properly. OR, you could have Global packages of previous versions that are overriding what you have installed. Double-check you don't have any old versions in your /AppData/Roaming/npm/node_modules directory and if so, delete them.

Missing TypeScript

TypeScript is necessary to run Coveo Headless. You may need to install it as the package.json doesn't explicitly call it out. To do so, run the following:

    npm install typescript
    

It's also possible that if when you created a react project, you didn't create it based upon a typescript template. It's also possible you're missing the tsconfig.json file itself.

Could Not Find A Declaration File For Module

If you see the error message that resembles Could not find a declaration file for module 'react/jsx-runtime'. then I would recommend running the following to ensure the types are properly installed for development.

    npm i --save-dev @types/react-dom
    

Keep In Mind

These are the early days of Coveo Headless, but already we see tremendous promise for it given the popularity of platforms like React, VueJs, etc. I'm looking forward to covering this in further detail in the future as more releases come out.