Set up Node.js [ Typescript, Docker, VS Code debugger ] development environment

In this article, we are going to try setting up a development environment for Node.js service using Typescript, Docker, and VS Code debugger. Keep in mind that this setup may not suit all your needs and represents something that worked for me a couple of times. In some next articles, I’ll cover more detailed way how to set up other tools, like code formatting and file structure that works for me.

Prereqs 🧱

Prerequisites for following this article are to have npm, node, VSCode, and docker & docker-compose installed. Also, you should create a directory and initialize a project using the npm init command.

Inside the project directory we need the next packages as devDependencies for a starting point:

• esbuild — you can opt to use different build tool
• esbuild-node-tsc
• nodemon
• typescript
• @types/node

Install them by issuing the command:

npm i --save-dev esbuild esbuild-node-tsc typescript nodemon @types/node

This is how our directory should look like

TSpilation⚡

Next, we want to set up TS by creating tsconfig.json

The tsconfig.json file can be configured per your preferences but what’s important is to have sourceMap set to true as well as specified outDir.

Also, create the empty app.ts file inside the src folder.

Next, we want to try out this config by creating a build script and running it. Add scripts section inside package.json file and create build script like this.

etsc command is a command for esbuild-node-tsc. It uses esbuild as the main bundler and sets a default esbuild config for Node.js & TS setup using the previously configured tsconfig.json. More on how it works you can find at esbuild-node-tsc github. This is completely up to you which build tool you want to use, for the sake of simplicity I have choosen the etsc but you can use Webpack, plain esbuild, or whatever fits your needs and preferences the best. Just don’t forget to set your tool to generate source maps as those are going to be crucial for the debugger that we are going to set later.

After running the npm run build you should have dist (or however you named the outDir) created with app.js and app.js.map files inside

Perpetuum mobile🔁

So far so good. The next thing we want to do is set up the nodemon just to make our life easier.

Create nodemon.json file inside the root project directory and put the next configuration inside. Also, we want to update the scripts section inside package.json to run the app in development mode.

This configuration is quite straightforward. The only field that’s maybe less known is the legacy watch which is needed for running the app inside of the container environment.

Also, I hope you noticed that the exec command after building runs the node app using two parameters --enable-source-maps --inspect=0.0.0.0:9229 . First of those enables source maps for our debugging when printing the stack trace. Also, keep in mind that this flag --enable-source-maps is still experimental and should not be used as is inside production. There are also some issues reported regarding this feature. The other one enables a debugger to be attached at port 9229 and we need this one for later when we are going to attach VS Code debugger to it.

If you now run npm run start:dev and visit http://localhost:8080/ you should see the message our service returns.

Dockerize it! 🐳

Now we are ready to dockerize this app before we start rocking it seamlessly.

Create Dockerfile, .dockerignore, and docker-compose.yml files in the root directory of the project.

First, we tell Docker, inside .dockerignore, that it should ignore node_modules and dist directory when performing the copy.

Next inside Dockerfile we configure it to use node v16 as the base image, and set WORKDIR which is a dir where the next commands are going to be invoked. Then we copy package.json and package-lock.json files and run an npm install command to install the dependencies. After dependencies installation is finished we copy all other files inside the image (without node_modules and dis which are ignored), expose the 8080 port, and set the default command to be invoked at container start.

This docker-compose setup is also straightforward. We tell the docker-compose which directory to use when searching for Docker file with build: . field, and which command to run as well as which ports to expose. Here we need to expose both ports for the app (8080) and the debugger (9229).

Quite an important part of the above config is the volumes we create. The first one is for the whole project directory which will enable us to edit files inside the container through VSCode and let the nodemon do its job. The second one lets us install dependencies locally, without the need of entering the container CLI and running the npm i command.

Let’s launch it…

Go inside the root project directory and run the command docker-compose up .

Your app should start running and you can see the logs. Try editing some of the source files to see if the nodemon does it’s job.

Disinsection🐛🔍

It is time for us to debug this piece of software. You can always go with console.log but I think I don’t need to explain why that’s a bad practice.

For this setup, we are going to use VS Code debugger. It may be intimidating at the beginning of use but you will see how simple it is to run it and you’ll forget about console methods soon after.

Inside the root project directory create a new dir named .vscode and inside of it create file launch.json.

With this configuration, we tell VS Code debugger to attach to the currently running process, at the port of 9229. Besides that, we configure the remote root directory of the container to usr/src/app, which matches the one from Dockerfile, as well as local root which matches our local directory. Very important is this outFiles config which tells VS Code debugger that the build code .js files are inside of dist directory so it knows where to find source and source maps and connect them to the .ts files.

Now go to your source .ts files, and place a breakpoint at the line of your choice, preferably some part of the code that is executed on each request.

Go to the Debug tab inside VS Code and run the debugger we configured previously.

Run the browser and visit http://localhost:8080/ and switch back to VS Code. You should see something like what is shown in the next image.

On the left, you can see the JS scopes currently active.

One more note: If you are using WSL, keep in mind that you want your VS Code to be up and running in remote WSL environment when starting a Debugger.

I hope you enjoyed this one and found it useful. There are possibly things that could be done or explained better but as I believe you should dig into it by yourself and not use this one as the only source of truth. If you have any suggestions or find any mistakes please inform me about it. 👋

Nikola Nedeljkovic, Software Engineer