-
Tutorials
- 0: Environment Setup
- 1: Basic Configuration, Options, and Markup
- 2: Interact With the Search Interface and Component Instances
- 3: Understanding the Event System
- 4: Modify the Query
- 5: Result Templates
- 6: Usage Analytics
- 7: Interact With Component States
- 8: Configure Your Own Search Endpoint
- 9: Advanced Integration With Custom TypeScript Component (Configuration)
- 10: Advanced Integration With Custom TypeScript Component (Implementation)
JavaScript Search Framework Tutorial 9: Advanced Integration With Custom TypeScript Component (Configuration)
This tutorial covers more advanced integration topics. It’s not necessary to go through this step in order to integrate Coveo to any website.
By referring only to the previous tutorials, you can do everything that will be explained here.
Doing a pure JavaScript implementation is totally legitimate and will always be supported (see Implement a Custom Component in JavaScript). You could also use any other language that can compile to JavaScript.
This tutorial explains how to configure a TypeScript project in conjunction with the Coveo JavaScript Search Framework. These explanations should help you get a better understanding of the inner workings of the framework, allowing you to write a solid implementation.
Since the source code of the Coveo JavaScript Search Framework is originally written in TypeScript, it also makes a lot of sense to explain this technology in this tutorial.
If you significantly modified the ./bin/index.html
page in previous tutorials, you can undo these changes by rebuilding the project. To do so, run the following command line in a terminal from the root of the tutorial project folder:
npm run build
Tutorial Project Structure
If you want to integrate custom components written in TypeScript, it’s important that you understand how the tutorial project is setup.
package.json
If you’re unfamiliar with the Node.js environment, this section will be difficult to understand. This tutorial assumes that you know how setup a basic Node.js project and have already done so. If you need to learn more about Node.js, many high quality tutorials are available on the Internet.
In the tutorial project, all required dependencies are installed and the ./package.json
file is already configured.
However, if you’re starting a new project from scratch, you can install the required dependencies like this:
-
The
coveo-search-ui
dependency:npm install --save coveo-search-ui
-
The
typescript
dependency (see TypeScript):npm install --save-dev typescript
-
The
webpack
dependency (see webpack module bundler):npm install --save-dev webpack npm install --save-dev webpack-dev-server npm install --save-dev ts-loader npm install --save-dev webpack-fail-plugin
The previous command lines will also install the following dependencies:
-
The
webpack-dev-server
dependency (see webpack-dev-server). -
The
ts-loader
dependency (needed for webpack to load TypeScript files properly, see ts-loader) . -
The
webpack-fail-plugin
(needed so webpack can fail properly when TypeScript compilation fails, see webpack-fail-plugin).
-
tsconfig.json
The ./tsconfig.json
file allows the TypeScript compiler to know what compiler options and what files should be used for your project.
{
"compilerOptions": {
"module": "commonjs",
"target": "es5",
"declaration": false,
"outDir": "./bin"
},
"files": [
"node_modules/coveo-search-ui/bin/ts/CoveoJsSearch.d.ts",
"src/Index.ts",
"src/ui/HelloWorld.ts"
]
}
To learn more about the tsconfig.json
file and the TypeScript compiler options, see tsconfig.json and Compiler Options.
In the "files"
section, you can see three files: two of them are from the tutorial project (Index.ts
and HelloWorld.ts
).
The CoveoJsSearch.d.ts
file won’t produce any JavaScript code when the project is compiled. It only references the base module from the framework, which provides auto-completion for class and method names as well as parameter types.
webpack.config.js
Webpack is a very complete (and complex) module bundler that makes it possible to create working JavaScript bundles. In the tutorial project, the ./webpack.config.js
file looks like this:
const webpack = require('webpack');
const minimize = process.argv.indexOf('--minimize') !== -1;
const colors = require('colors');
const failPlugin = require('webpack-fail-plugin');
if (minimize) {
console.log('Building minified version of the library'.bgGreen.red);
} else {
console.log('Building non minified version of the library'.bgGreen.red);
}
// Fail plugin will allow the webpack ts-loader to fail correctly when the TS compilation fails.
var plugins = [failPlugin];
if (minimize) {
plugins.push(new webpack.optimize.UglifyJsPlugin());
}
module.exports = {
entry: ['./src/Index.ts'],
output: {
path: require('path').resolve('./bin/js'),
filename: minimize ? 'coveo.extension.min.js' : 'coveo.extension.js',
libraryTarget: 'umd',
library: 'CoveoExtension',
publicPath: '/js/'
},
resolve: {
extensions: ['', '.ts', '.js'],
},
devtool: 'source-map',
module: {
loaders: [
{test: /\.ts$/, loader: 'ts-loader'}
]
},
plugins: plugins,
bail: true
}
Here are the most important parts to understand in this configuration:
entry
specifies which file you want to use to create a bundle. It’s from this file that webpack will create the resulting dependency tree.
In this file, you should export all the classes and functions that you want to make available in your namespace.path
andfilename
specify where you want the compiled JavaScript file to be created.libraryTarget
being set to'umd'
means that it will be possible to use your library in a web browser or load it from another CommonJS module (see UMD).library
specifies the namespace under which your module will be available in the web browser.
Since this option is currently set to'CoveoExtension'
, if you export a class namedFoobar
, this class will be available underCoveoExtension.Foobar
in the browser.loaders
specify an array of webpack loaders that you want to use. In the case of the tutorial project, only one loader (ts-loader
) will handle all TypeScript files (files matching the/.ts$/
regex).
dev.server.js
This file is a Node.js script that will start a webpack dev server so that you can quickly iterate over your components.
You can start the server by typing the following command line in a terminal:
node dev.server.js
Or more simply:
npm run watch
What’s Next?
You should now proceed to JavaScript Search Framework Tutorial 10: Advanced Integration With Custom TypeScript Component (Implementation).