Develop Hosted Search Pages With Coveo Turbo
Inserting the Coveo Hosted Search Page Coveo for Sitecore JSS component in a website page, combined with the use of Coveo Turbo, simplifies and streamlines the search page development process.
The Coveo Turbo CLI-based tool lets you develop locally and then deploy search pages to a Coveo organization as a hosted search page. Coveo Turbo is geared to be used with the Coveo Hosted Search Page component.
Development Environment Setup
Before using Coveo Turbo for your Coveo search solution development, you need to set up your environment.
The content in this section assumes your developers will collaborate and push changes to their search pages into your Coveo sandbox organization (which should be a part of your UAT environment). This setup ensures optimal team productivity and access to representative indexed data, while limiting the extent to which the developers can access and modify content and configurations in the sandbox organization.
Accordingly, some preliminary setup steps below are specifically assigned to a lead developer or administrator having administrator privileges in the sandbox organization (and hereafter referred to as the Administrator).
Installing Node JS and NPM
To install Coveo Turbo, you need a Node JS environment with npm. You can download and install both from the node.js website. Coveo Turbo requires at least version 12 of Node.js.
Installing the Coveo Turbo CLI
To install the CLI, use the following command:
npm install --save-dev @coveops/cli
Creating an API Key in Your Coveo Sandbox Organization (Administrator)
To create the API key
Access the API Keys page of the Coveo Administration Console.
Click Add key.
In the Add an API key panel, in the Configuration tab, provide a
In the Privileges tab, provide the following access levels:
Domain Resource Access level
Creating a Coveo Turbo Project With a Search Page (Administrator)
You can create a new Coveo Turbo project including a basic search page as follows:
Open your preferred code editor.
Create a new folder to serve as your Coveo Turbo project repository root folder.
From the root of your Coveo Turbo repository, run:
coveops create:project <NEW_COMPONENT_NAME> --create-component --with-styles --with-page
<NEW_COMPONENT_NAME>with your component name.
An empty component definition is required by the
create:projectcommand to be able to deploy the search page later on in the process. We won’t use the component definition or make any changes to the generated
.tsfiles for the remainder of the process.
Coveo Turbo CLI commands may be invoked in a number of ways, whether the CLI is installed globally or as a dev dependency (see CLI command usage).
Among other items, the
create:project command creates:
the necessary project files
a basic search page (
a new component
.tsfile in the
the component stylesheet
.scssfiles in the
Setting Project Environment Variables (Administrator)
Coveo Turbo lets you serve, browse, and test a local Coveo search page. Having representative items to work with eases the testing of your local Coveo-powered search page. To do so, you want your project to connect to your sandbox Coveo organization and to share connection configurations among developers.
.env.distfile, set values for the
COVEO_TOKENenvironment variables. For Coveo organizations not in the US deployment region, additional environment variables must be initialized (see Deploy to Another Region or HIPAA).
Copy the content of the
.env.distfile into the
.envfile, change the
SERVER_PORTvalue, if necessary.
It’s now time to set up a repository for the project to version control your search page and stylesheet code.
Search Page Development
Adding and Configuring Search Page Components
pages/index.html search page, is a matter of:
adding an HTML tag with the component-specific and
Coveo-prefixed CSS class in the search page (e.g.,
configuring the component using element attributes whose names are the component option name, in lower case, prefixed by
data-and with each word of the component option separated by a dash (e.g.,
<div class="CoveoSearchbox" data-enable-omnibox="true"></div>).
Should you want to create and edit other search pages, you can add a search page to your project using the Coveo Turbo Create a Page command.
Testing a Search Hub
Coveo search query results and their order in a result list depend on the search hub each search query is tagged with.
To properly emulate and test a specific search interface, you need to set the corresponding
COVEO_SEARCH_HUB value in your
.env file (see Set the Search Hub).
Your administrator should provide you with the necessary search hub value(s) and details as to expected search result patterns when targeting a given search hub.
For your search page stylesheets, Coveo Turbo lets you either:
target CSS files on your corporate website by adding
<link rel="stylesheet">tags in the search page
add your search page styling in the
There’s no need to add any CSS-related import statement to your component
Configuring Result Templates
Building the Project
Building the project creates a
dist folder with the compiled
coveops build <NEW_COMPONENT_NAME>
<NEW_COMPONENT_NAME> with your component name.
Serving the Search Page Locally
The Coveo Turbo
serve command starts a Node server designed to browse any of the HTML pages in the
pages folder of your project.
The compiled distributable may be used in those pages as a static resource.
The following command serves your project pages on
<SERVER_PORT> is the value of the
SERVER_PORT variable specified in your
Deploying a Search Page to Your Sandbox Coveo Organization
Coveo Turbo HTML search pages may be deployed to a Coveo organization as hosted search pages. When running the deploy command, you should specify the source name (i.e., the file name of the search page in your project) and the target name (i.e., the name of the hosted search page in your Coveo organization) as arguments. If a hosted search page with the target name already exists in your Coveo organization, it gets overwritten.
The following command deploys the
pages/index.html page in your project to create or update a hosted search page called
newplatformpage in your Coveo organization.
coveops deploy index newplatformpage
Search Page Deployment to Your Production Coveo Organization (Administrator)
Once a search page has undergone the necessary testing in your User Acceptance Testing (UAT) environment, you can apply the changes to the corresponding search page in your production Coveo organization. To do this, you have a couple of options:
You can push the search page from your Coveo Turbo project to your production Coveo organization. This entails having an API key set up with the necessary privileges in that Coveo organization (see Create an API Key in Your Coveo Sandbox Organization).
To copy one or multiple sandbox Coveo organization search pages along with other sandbox Coveo organization resource configurations to your production Coveo organization, Coveo provides a handy resource snapshot feature (see Migrate Changes Between Cloud Organizations).