Coveo Turbo CLI Reference

Table of content:

• Installation
• Usage
  • Build
  • Serve
  • Create a Project
  • Create a Component
  • Create a Stylesheet
  • Adding images
  • Create a Page
  • Deploy a Page
  • Create Locales
  • Create a Translation
  • Update a Translation
  • Create a Readme
  • Create a Docker Environment
  • Create a Query Pipeline

Installation

To install the CLI, use the following command:

npm install --save-dev @coveops/cli

Usage

Replace the COMMAND with the appropriate one from the table below with its corresponding arguments and options.

Installed globally:

coveops COMMAND

Installed as a dev dependency (recommended to track versioning):

./node_modules/.bin/coveops COMMAND

Alternatively on Windows: .\node_modules\.bin\coveops CountedTabs COMMAND

Executed via npx:

npx @coveops/cli COMMAND

Build

This command uses a standard Webpack configuration to build and bundle the project for distribution.

You can also add the command to your package.json scripts to continue using familiar hooks like npm run build

Examples:

Basic use case:

./node_modules/.bin/coveops build TestComponent

To watch:

./node_modules/.bin/coveops build TestComponent --watch

To use vanilla JavaScript:

./node_modules/.bin/coveops build TestComponent --template vanilla

To specify an alternative directory containing a index.scss located at src/stylesheets:

./node_modules/.bin/coveops build TestComponent --styles-path src/stylesheets

SwapVar

Coveo injects custom components into its root object by using a custom utility called SwapVar. With Coveo Turbo, this utility is injected into the root index of the code during build time, so no additional effort or integration is necessary in a project.

Thanks to the SwapVar utility, the exported component is referenced in implementation JavaScript code as such:

Coveo.TestComponent

Without the SwapVar utility, achieved by using the disable-swapvar option in the build, the exported component library is referenced in implementation JavaScript code such:

CoveoTestComponent

Serve

This command starts a Node server designed to:

• Serve the compiled distributable as a static resource that can be loaded onto the page.
• Serve installed components in the node_modules folder under the @coveops scope as static resources that can be loaded onto the page.
• Serve all HTML pages in the pages folder.
• Pass parameters from the environment or CLI arguments to the running instance to be used in the application via the demoConfig variable declared in /config.js when the server starts.

If no org-id or token are used, then a sample Coveo organization with some already indexed content is used.

Examples:

Basic use case:

./node_modules/.bin/coveops serve --org-id <ID HERE> --token "<TOKEN HERE>"

To use a different port:

./node_modules/.bin/coveops serve --port 3000 --org-id <ID HERE> --token "<TOKEN HERE>"

Some of the arguments have a corresponding environment variable that can also be used by the server:

Compiled Component

The compiled component has its resources served at the following endpoints.

In some cases, only JavaScript or CSS may be available.

• ./component.js
• ./component.css

Installed Components

The installed components have their resources served at the following endpoints.

In some cases, only JavaScript or CSS may be available.

• components/<name>.js
• components/<name>.css

The <name> represents the name of the component within the @coveops scope.

For example, importing a component installed from @coveops/test-component will have the following assets served:

• components/test-component.js
• components/test-component.css

Alternatively, these installed components can be bundled into the library via the corresponding index file in the src before being built.

Injected Parameters

The serve command generates a JavaScript snippet that is injected into the page by importing the /config.js file, which contains some of the information that was passed through environment variables or CLI arguments in a global demoConfig variable. This allows a page to remain decoupled from the test settings to allow portability between environments where component-level dependencies permit.

The following information is passed in the demoConfig object and is available to use within the application at runtime:

Create a Project

This command adds the necessary files to kick-start a project to create a shareable component and optionally the component itself.

When ran using npx, the create:project utility initializes a package.json and installs itself as a dev dependency for you.

Example usage:

To quick-start a new project:

npx @coveops/cli create:project TestComponent --create-component --with-styles --with-page

To use in a project where @coveops/cli is installed:

./node_modules/.bin/coveops create:project TestComponent

To use vanilla JavaScript:

Note: Building a component requires the same template option to be passed to the build command.

./node_modules/.bin/coveops create:project TestComponent --template vanilla

To create a component at the same time as a new project:

./node_modules/.bin/coveops create:project TestComponent --create-component

To create a component with styling at the same time as a new project:

./node_modules/.bin/coveops create:project TestComponent --create-component --with-styles

To create a page at the same time:

./node_modules/.bin/coveops create:project TestComponent --with-page

To setup locales at the same time:

./node_modules/.bin/coveops create:project TestComponent --setup-locales fr es-es

Create a Component

This command creates a blank component to be used to canvas for your needs. It is currently available as vanilla and typescript types.

• A Typescript template component creates a class and associate the build tools to use the TypeScript compiler.

• A Vanilla template component creates a simple module bridge to permit any JavaScript code to be bundled. It associates the build tools to use the JavaScript bundler.

Example usage:

./node_modules/.bin/coveops create:component TestComponent

To use vanilla Javascript:

Note: Building a component requires the same template option to be passed to the build command.

./node_modules/.bin/coveops create:component TestComponent --template vanilla

To create a component with styling at the same time as creating a new project:

./node_modules/.bin/coveops create:component TestComponent --with-styles

Create a Stylesheet

This command creates a blank stylesheet to be used to canvas for your needs. It is currently available as sass and vanilla types.

• A Sass template stylesheet creates a file per class and bundles it in a shared index.

• [Experimental] A Vanilla template will create a file per class and bundle it in a shared index.

Example usage:

./node_modules/.bin/coveops create:stylesheet TestComponent

To use vanilla CSS:

Note: this feature isn’t fully supported and may cause issues. For now, it is recommended to use the Sass template.

./node_modules/.bin/coveops create:stylesheet TestComponent --template vanilla

Adding images

[CLI Version 0.14.0+]

Some implementations require custom icons or images to be displayed as part of their templates. To achieve this, follow these steps:

1. Add your images to the images folder of the src folder (.\src\images). If that folder does not yet exist, you need to create it.
2. If you are not already running the watch command, build the project with the make build command. The images should now be copied to the dist folder.
3. Refresh the page or run the make serve command. Images should now be exposed under /images, and can be used in the HTML markup or in CSS.

When referencing an image in CSS, use the relative path to the images folder in src.

When referencing an image in the HTML markup, use the relative url path starting with /images.

The folder path will be respected one-to-one with the source. For example, if an image is located at src/images/subfolder/image.png, the output will be dist/images/subfolder/image.png. Its CSS use will be ../images/subfolder/image.png, while it will be http://localhost:<PORT>/images/subfolder/image.png in HTML.

Component Initialization

The Coveo component registration allows for two main strategies to load a component once the scripts and markup are present on the page: Eager and Lazy.

The @coveops/turbo-core library contains useful decorators that make it simple to choose the initialization structure without requiring boilerplate code. All of the strategies fallback to component if the LazyInitialization class isn’t present when importing Coveo.Lazy.js

This feature is currently only available for TypeScript Components.

./node_modules/.bin/coveops create:component TestComponent --init-strategy component

Create a Page

This command creates a folder with a generated search page to be used for basic debugging.

Example usage:

./node_modules/.bin/coveops create:page

Note: once served, the page is available at localhost:/index.html

To add another page

./node_modules/.bin/coveops create:page knowledge

Note: once served, the page is available at localhost:/knowledge.html

To use a different path

Note: changing the path of the page requires using the same path when serving it.

./node_modules/.bin/coveops create:page --path test

To use a specific page layout

Note: changing the path of the page requires using the same path when serving it.

./node_modules/.bin/coveops create:page --layout servicenow-agent-panel

Available Page Layouts

[CLI Version 0.14.0+]

Deploy a Page to the Coveo Platform

This command creates a new page and deploys the specified page and its minified JavaScript and CSS there.

This feature requires the project to already be built. It only deploys the compiled code.

Example usage:

./node_modules/.bin/coveops deploy

To deploy a specific page to a specific Search page in Coveo:

./node_modules/.bin/coveops deploy index page

By default, creating a page creates an HTML page called index. The page in the Coveo Platform can be named arbitrarily and differently.

Some of the arguments have a corresponding environment variable that can be used with the deploy command.

Deploy to Another Region or HIPAA

For each region, the API endpoints that Coveo will communicate with will be different. By default, Coveo Turbo uses the US data-center domain names and sets them as defaults for you but it can accomodate different regions with additional configuration.

In the .env file, add the following environment variables and specify the data-center:

• COVEO_REST_URI
• COVEO_SEARCH_PAGE_HOST

For example, the EU data center will require the following configuration:

COVEO_REST_URI=https://platform-eu.cloud.coveo.com/rest/search
COVEO_SEARCH_PAGE_HOST=search-eu.cloud.coveo.com

For more information on how to obtain your data region, you can consult the Multi-Region Deployment Configuration documentation.

Similarly, the corresponding endpoints will be different for HIPAA implementations and the same configuration parameters will need to be passed with the corresponding HIPAA endpoints.

Here’s an example of configuration you’d add to your .env for HIPAA for the US data-center:

COVEO_REST_URI=https://platformhipaa.cloud.coveo.com/rest/search
COVEO_SEARCH_PAGE_HOST=searchhipaa.cloud.coveo.com

Create Locales

This command creates and scaffolds standardized locale dictionaries for the project.

After running this command, a build is necessary for changes to take effect.

Example usage:

./node_modules/.bin/coveops create:locales fr es

To also set up the LocalizationManager:

./node_modules/.bin/coveops create:locales fr es-es --setup

To use a different default locale as a base, you can specify it as follows:

./node_modules/.bin/coveops create:locales en es --default fr

To use a different filetype to manage the dictionary, you can specify it as follows:

./node_modules/.bin/coveops create:locales en fr --type yaml

Create a Translation

This command creates all the necessary translation entries or empty placeholders for a given word.

This operation does not replace values that already exist. To update those, use the update:translation command.

For changes to take effect, a build will be necessary after running this command.

Example usage:

./node_modules/.bin/coveops create:translation Word --en Word --fr Mot

Note: In order to recognize English and French, the create:locales command was ran prior, as such.

Since, by default, English is the default language, only fr needed to be specified.

./node_modules/.bin/coveops create:locales fr 

To target a specific component:

./node_modules/.bin/coveops create:translation Word --en Word --fr Mot --target DynamicFacet

If you used a different filetype than json when creating the locale, you can specify it as follows:

./node_modules/.bin/coveops create:translation Word --type yaml --en Word --fr Mot

To use translations:

1. Ensure @coveops/localization-manager is installed as a dependency and registered as per instructions on the component.
2. Expose the translation file as per the chosen locale for the page. This file will add a variable LOCALES to the global namespace which can then be used throughout the process. The LOCALES variable will have the additional locales and is upkept with these CLI commands.

    <script src="locales/fr.js"></script>
   

3. Run the LocalizationManager before Coveo initializes.

    CoveoLocalizationManager(LOCALES);
   

Update a Translation

This command updates the translation entries for a given word, only for the locales specified in the options.

For the changes to take effect, a build is necessary after running this command.

Example usage:

./node_modules/.bin/coveops update:translation Word --fr Mot

Note: In order to recognize English and French, the create:locales command was ran prior. Since, by default, English is the default language, only fr needed to be specified.

./node_modules/.bin/coveops create:locales fr 

To update a translation on a targeted component:

./node_modules/.bin/coveops update:translation Word --en Word --fr Mot --target DynamicFacet

If you used a different filetype than JSON when creating the locale, you can specify it as follows:

./node_modules/.bin/coveops update:translation Word --type yaml --en Word --fr Mot

Create a README file

This command creates or overwrites an existing README.md file with a standard template that uses contextual information provided to it.

This command shouldn’t be necessary when creating a new project, as this functionality is bundled by default.

Example usage:

./node_modules/.bin/coveops create:readme TestComponent --description "This is a sample description"

Create a Docker Environment

This command creates or overwrites an existing docker-compose.yml file with a basic compose setup that includes a server running NodeJS v12 and uses the bundled Makefile to install, build, and serve the project with the configured environment variables.

Example usage:

./node_modules/.bin/coveops create:docker

To get started, run:

docker-compose up -d

To access a bash shell within the environment:

docker-compose exec server bash

To only run the server during the up phase, and handle the install and build commands manually, you can remove the setup and build directives from the entrypoint field in the docker-compose.yml file.

Create a Query Pipeline

[CLI Version 0.12.0+]

This command creates a query pipeline in the Coveo organization. This pipeline has a condition set to the search hub specified in the command.

Example usage:

./node_modules/.bin/coveops create:pipeline SearchPage

To use a different searchHub:

./node_modules/.bin/coveops create:pipeline SearchPage --search-hub SearchPageSearchHub

To not use a searchHub:

./node_modules/.bin/coveops create:pipeline SearchPage --without-search-hub