How to get auto restart and breakpoint support with Typescript and Node

Creating a great typescript experience with node

When I first tried to use typescript on a NodeJs project I struggled to find a good guide explaining how to get setup. So I’ve decided to write one myself. It’s extremely opioniated, but I’ve found this works great for me. My hope is that it will for someone else as well.

During the last 12 months I’ve setup countless Flow and Typescript projects. I’ve been experimenting with multiple editors, test frameworks and build tools. I initially started out with boilerplates, but lately I’ve found it easier to simply create the setup from scratch, with a few exceptions. The benefit of doing that, is that I understand every part of the project. And can add to it on a need basis.

In this guide, I’ll show you how to setup a basic setup with typescript and node. And then how to get a very effective setup with breakpoint support (in VSCode), unit tests and auto restart. If you’re familiar with the basic steps, you can skip right to step 3 and 4 where the auto-reloading and breakpoints get introduced

1: Basic Setup

Lets start out in an empty directory. In my case I’m starting out in a sample project folder named typescript-node. In this step we’ll create a simple setup for writing an express server in typescript.We’ll start by creating the following files

$ npm init
$ mkdir src && touch src/server.ts
$ tsc --init

Which should give you the following structure

- src
   server.ts
package.json
tsconfig.json

Next we’ll add the required dependencies to the project. You can use either yarn or npm for this step (I’ll stick to yarn in my examples).

yarn add express
yarn add --dev typescript @types/express

Next we’ll add a super simple server

And add the following to your npm scripts section in package.json:

And replace the content of your tsconfig.json with the following:

That’s it. You should now be able to run npm startin your terminal and see your server running:

2: Adding unit tests with Jest

I’ve found that getting a test setup running, that is simple to use and run is extremely important. If I don’t me and the other developers tend to forego unit tests in the heat of battle. And once that starts happening it’s extremely hard to get test coverage back on track.

Ever since I got familiar with Jest, I’ve fallen in love with both it’s speed, ease of use, output and the more importantly in this case: how easy it is to integrate with typescript. To get started, lets add the following dependencies:

yarn add --dev ts-jest jest @types/jest

And add the following to your package.json (I added two extra scripts to the scripts section)

Next we’ll add a dummy.test.ts to the src directory, to verify that the test runner is working as expected.

We’re all set. You can now run npm test to run the test suite once or npm run test:watch to run it continously:

3: Adding auto restart of the server when code changes

Another neat addition when developing in node, is having the server restart everytime you change your code. However, making this work properly with typescript can be a bit tricky, if you’ve never tried it out before. But it’s actually really simple with nodemon and ts-node. So lets add those:

yarn add --dev nodemon ts-node

And I like to keep my nodemon config in a seperat nodemon.json to make the npm scripts a tad easier to read. So create nodemon.json in the root of the project with the following content:

We’ll modify our start script to use ts-node (this ensures nodemon won’t crash when typescript does’nt compile) and add a dev script, that runs nodemon:

You can now run npm run dev and have your server auto restart everytime you make a change:

4: Adding support for breakpoints in Visual Studio Code

The above will be enough to make you productive when writing node in typescript. However, having breakpoints can really speed up your debugging experience. It’s something that most developers in Java or other statically typed languages are quite used to, but that I’ve found most node developers rarely use. But once you get used to it, it’s extremely painful to go back to “console.log” debugging.

The first step is to run node with the inspect flag. (should be supported from node 6.3 and up. But I’ve only tested it with node 7.9.0). So lets change our start script to the following:

Next we’ll add the following to the vscode launch.json file in our project. You can either have vscode generate it or manually add it to the .vscode directory at the root of your project. You can read more about vscode debugging here.

Next we’ll add a default endpoint to our server to test out that breakpoints work as expected.

And we’re good to go. Start the server with npm run dev and start debuging by pressing F5 or navigating to the debug tab in vscode. Try adding a breakpoint at line 8 in my sample above and hit localhost:8000. You should now see vscode stop at your breakpoint. This enables you to both inspect all variables currently in scope and modify them with vscode’s debug tab.

The debug tab at the bottom enables you to manipulate variables in scope. While hovering over variables in scope enables you to inspect them with the dropdown menu above.

That’s it. You can now code away, with an auto restarting server and remote debugging enabled in vscode. You don’t even need to restart the process in vscode — it reattaches automatically. One caveat though is that it clears your breakpoints on every server restart. If you figure out how to solve that please let me know in the comments below! You can find the code for this guide in this repo: https://github.com/Aleksion/typescript-node-walkthrough

Have you found a better way to work with typescript and node? Or have I missed anything critical in my walkthrough? Let me know here or on Twitter.
Liked this? Please don’t hesitate to ❤ it & share with your friends!