Debugging TypeScript in VS Code without compiling, using ts-node

3 min readApr 25, 2017

Firstly, apologies for a lack of content for the last few weeks! I’ve been busy working on my JavaScript data framework RevJS, getting it ready for use in some upcoming projects!

I just wanted to share with the community some recent learnings around debugging TypeScript in VS Code.

I wrote in Part 3 of my JS article series about how to set breakpoints and inspect variables in TypeScript projects. The only downside of the method I described is that you have to remember to transpile your TypeScript code to JavaScript first before running it. Granted, this is just a case of pressing CTRL+B, but when you are writing a lot of code, this can get annoying!

This article describes the tooling and configuration needed to allow you to run and debug TypeScript code and tests directly, without a separate build step!

(if you would prefer to just grab the repo and get going, click here! :) )

UPDATED 18/09/2017 — Thanks to @valVK and @borekb for the recent contributions to the repo!

TS-NODE

Firstly, in order to run TypeScript directly, we need a run-time environment that supports it.

ts-node is an awesome library which adds a “require hook” to NodeJS that allows you to require TypeScript files directly from a JavaScript file

For example:

require('ts-node').register();// Now we can load and run ./my-typescript-code.ts...
require('./my-typescript-code');

NodeJS 6.3+ V8 Inspector Protocol

For reliable debugging, NodeJS 6.3 added “V8 Inspector Protocol”, which allows you to debug your NodeJS apps using chrome dev tools!

Visual Studio Code has also now added support for this protocol, and you’ll see it mentioned in the configurations in the next section.

TS Config

To allow breakpoints to work, we need to enable source maps in our tsconfig.json as shown below:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "noImplicitAny": true,
    "outDir": "./dist",
    "sourceMap": true
  },
  "include": [
    "src/**/*"
  ],
}

UPDATE: With the most recent versions of the tools, it seems enabling sourceMaps may no longer be required.

Debugging TS Files

To add a VS Code Task for debugging TS files, you’ll need to edit the launch.json file for your project (more info here) and add the following into the configurations section:

{
    "name": "Current TS File",
    "type": "node",
    "request": "launch",
    "args": ["${relativeFile}"],
    "runtimeArgs": ["--nolazy", "-r", "ts-node/register"],
    "sourceMaps": true,
    "cwd": "${workspaceRoot}",
    "protocol": "inspector",
}

This configuration:

Sets up a node task that starts the currently open file in VS Code (the${relativeFile} variable contains the currently open file)
Passes in the --nolazy arg for node, which tells v8 to compile your code ahead of time, so that breakpoints work correctly
Passes in -r ts-node/register for node, which ensures that ts-node is loaded before it tries to execute your code
Sets the working directory to the project root - ${workspaceRoot}
Sets the node debug protocol to V8 Inspector mode (see above)

With that in place, go select a .ts file in your project, and run the “Current TS File” debug task!

Debugging Mocha Tests

To add a task for debugging Mocha Tests, you’ll need to add the following configuration to your project’s launch.json

{
    "name": "Current TS Tests File",
    "type": "node",
    "request": "launch",
    "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
    "args": ["-r", "ts-node/register", "${relativeFile}"],
    "cwd": "${workspaceRoot}",
    "protocol": "inspector"
}

This configuration:

Sets up a node task, that launches mocha
Passes a -r argument, that tells mocha to require ts-node
Passes in the currently open file - ${relativeFile}
Sets the working directory to the project root - ${workspaceRoot}
Sets the node debug protocol to V8 Inspector mode

With that in place, open a .ts file containing mocha unit tests, set a breakpoint, and run the “Current TS Tests File” VS Code debug task.

Sample Project

I’ve created a simple TypeScript project that includes all of the configuration above, here. Hope its helpful!