Debug Typescript using Node Runtime Environment in VS Code

Today, we will learn how we can debug typescript using node runtime environment in VSCode.

Typescript Compilation

So to begin debugging, we need to understand how typescript is files are run by Node. Well actually, Node is not able to run typescript files directly. So we need to transpile typescript files into javascript files and then Node runs those transpiled javascript files. To transpile typescript files, we can use tsc, typescript compiler.

To transpile/compile typescript file into javascript files, we need to define some configuration in the root folder of project in tsconfig.json file. Here is the very basic tsconfig.json:

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
    "sourceMap": true,
  }
}

In above json, we have:
rootDir, that tells tsc where are our application files.
ourDir, that tells tsc where tsc need to make transpiled javascript files.
sourceMap, that tells tsc to linkup transpiled javascript files with typescript files. This link is necessary for debugging, so that node debugger show you the typescript file but actually debugging the linked transpiled javascript file.

Now you can run the command npx tsc and see the output directory dist in your project.

So now we know how typescript files are actually run by Node. Let's move to next step.

VS Code Configuration

Now we need to configure VS Code so whenever we want to debug, it runs a set of commands before debugging.
We need to create launch.json, a configuration file for VS Code, in the root of the project and have these configurations:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TS Files",
      "program": "${workspaceFolder}/src/app.ts",
      "skipFiles": ["<node_internals>/**"],
      "preLaunchTask": "npm: build",
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

version simply defines the version of this file.
configuration is an array of objects where each object represent configuration of respective command.
type, type of configuration.
request can either be launch or attach. Launch is for launching the app from the start and then attaching debugger. Attach is for attaching debugger on already running app. You can read more here.
program is the base file of your project, in this project's case, its /src/app.ts.
skipFiles is to skip file while debugging.
preLaunchTask is to do something, like building or transpiling TS files, before launching the debugger.
sourceMaps is to tell VS Code that we are not using project TS files, rather we are using transpiled JS files.
outFiles provides the location of transpiled JS files, which is /dist/**/*.js in our case, as we provided in the tsconfig.json

Now when you save this file, and go to Run and Debug tab of VS Code, looks like:

We can see our newly added command at the top:

We are almost done.

Add build command in package json

If you notice, in launch.json, we have a configuration:
preLaunchTask: 'npm: build'
this runs the command npm run build before attaching a debugger. But we haven't specified this command in package.json yet.
So open your package.json and add the following:

"scripts": {
    ...other commands
    "build": "tsc"
},

Here build is simply running tsc, which will transpile our TS files in JS files and store those in /dist (as provided in tsconfig.json) and our debugger use those sourceMapped files to debug TS files.

Run Debugger

Now add breakpoints wherever you want and run debugger by simply clicking play button beside our VS Code command in Run & Debug tab:

Congrats! we have our debugger running successfully:

PS: We can skip all these configuration and use Bun runtime environment to debug as it provides TS debugging out of the box

Hope you learned something today.
Happy Coding ❤️