Transpilers, compilers and the Node.js agent

Contrast supports applications written in languages that compile to JavaScript, such as CoffeeScript and TypeScript. The Node.js only instruments JavaScript. However, if you are using CoffeeScript or TypeScript, you can configure the transpiler to compile your application into JavaScript.

Note

Although Contrast functions with languages that compile to JavaScript, the source may not correspond directly with the resulting JavaScript. As a result, reported metadata - such as vulnerability line-of-code and filename - references the compiled result, not the original source.

Some languages, like TypeScript, require you to precompile your code before runtime. In these cases, the Node.js agent must point to the compiled entrypoint for your application.

To do this, set up the Node.js agent using the -r option:

scripts: {
    "test": "...",
    "start": "...",
    "contrast": "node -r @contrast/agent /path/to/transpiled/entrypoint.js"
}

Alternatively, languages like CoffeeScript run via a command line utility, which acts as a runner and compiles your application to JavaScript at runtime. It's possible to have Contrast's Node.js agent act as a runner for the runtime transpiler, which acts as a runner for your application. To set up Contrast as a runner:

  1. Provide the entrypoint to the transpiler instead of providing the entrypoint to your application as an argument. (You're essentially telling Contrast that your application is the transpiler.)

  2. Use the --appArgs setting to tell Contrast to pass this argument along.

In this example, Contrast is running with a CoffeeScript application:

scripts: {
    "test": "...",
    "start": "...",
    "contrast": "node-contrast /path/to/coffee/transpiler --application.args '/path/to/app/entrypoint.coffee'"
}