JavaScript Search Framework Tutorial 9 - Advanced Integration With Custom TypeScript Component (Configuration)

This tutorial covers more advanced integration topics. It is 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 Implementing 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.

npm run build

Tutorial Project Structure

If you want to integrate custom components written in TypeScript, it is important that you understand how the tutorial project is setup.

package.json

If you are 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 are 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"
  ]
}

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 will not 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 is 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. 
• pathand filename 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 named Foobar, this class will be available under CoveoExtension.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).