How to setup a simple Node.js project with TypeScript support in Visual Studio Code – Free and Open source IDE.

As I explained in previous post, TypeScript brings more order to Node.js projects, it’s especially useful for defining APIs for multi-modular projects. Now I will show you how to create simple project with dependencies.

Before we start

I assume you have Unix-like OS (if you are still on Windows, you can wait until Microsoft integrates Ubuntu in Windows, you can use Linux VM with VirtualBox or other virtualisation solution, or you can use Cygwin) and fairly recent version of Node.js installed. Of course, you can use Windows as well, but you may need to slightly adapt this tutorial.

Additionally, we need to install some npm tool modules globally, as they’re used in most of Node.js projects:

  • typings – TypeScript definition manager
  • typescript – stanalone TypeScript compiler

TypeScript project creation

We are going to create metrix-js-example – a simple metrics aggregator based on metrix-js. Here’s what it will do:

  1. Read array of objects from file data.json
  2. Iterate over that array and match every object against metrics defined with metrix-js rules
  3. Print input data and metric hits

First, we need to create and initialise project folder structure.

Visual Studio Code project setup

Visual Studio Code is a lightweight Free and Open source IDE that supports many languages and file formats through extension modules. It’s available on all major platforms and has TypeScript support out of the box.

At the start, we open the project we’ve just created (All screenshots taken from Visual Studio Code 1.1.1 on Mac OS).

We will start by importing our project. Select “File” > “Open” from main menu, then navigate to the project folder and press “Open” button.

Visual Studio Code - open TypeScript project

Visual Studio Code – open TypeScript project

Now we need to enable TypeScript compiler task for the project. To do that, open tsconfig.json file and:

  • add option watch (set it to true) in compilerOptions element – this required to make compiler detect source code changes and automatically recompile files
  • set option sourceMap to true in compilerOptions element – this required to enable map file generation required for interactive debugging

then save the file and update tasks configurations – press  Command+Shift+P then search for “Configure Task Runner” option and then “TypeScript – tsconfig.json”

Visual Studio Code - configure TypeScript compiler

Visual Studio Code – configure TypeScript compiler

Leave all default parameters

To start the compiler task use  Command+Shift+B . Additionally, you can open compiler output window using  Command+Shift+U .

Now we are ready to put our ideas into code. Right-click on src folder on left-side Explorer panel and type in desired file name – index.ts

We are going to use Node.js built-in module – fs to read data from data.json file.

Visual Studio Code - module not found

Visual Studio Code – module not found

As we can see, module fs is not recognised by TypeScript compiler even though it’s a standard Node.js module. How is that possible? TypeScript compiler is independent of Node.js and doesn’t have any knowledge of what’s implemented in Node.js and what’s not. This means that any module used in TypeScript project needs to have TypeScript definition of some sort.

There are two different types of such definitions:

  • internal definitions – when .d.ts definition file is put inside npm module and distributed with that module. This is a preferred way.
  • external definitions – when .d.ts definition file is created and maintained outside of npm module it describes. This should be used only when npm module doesn’t have a TypeScript definition file and you can’t add it. This sort of definitions is managed by command line utility – typings.

In our case, fs it’s not even an npm module, therefore we have to import its external definition

In the project root folder run

Prefix dt~ before module name is source for definition. dt stands for DefinitelyTyped repository. You can find all available definitions for node with search command

which should return something like

As we can see, it downloaded and installed TypeScript definitions under typings folder.

Now we need to stop compiler with   Command+Shift+B command (you need to confirm stopping corresponding task) and then start it again   Command+Shift+B  to force definition files reload.

Visual Studio Code - definitions installed

Visual Studio Code – definitions installed

In our project we are going to use external npm module – metrix-js which has to be installed with npm install command

Because this module has built-in TypeScript definitions we don’t need any extra steps for that.

We will implement desired logic in project main script file src/index.ts

and add data.json file into the root directory of the project

At this point our project is completed. As you can see, index.js and files have been generated by TypeScript compiler.

Visual Studio Code - final result

Visual Studio Code – final result

Running in Visual Studio Code

To configure launch configuration in Visual Studio Code, press  Command+Shift+P then search for “Open launch.json” option then “Node.js” option. Update file content:

  • set program to “${workspaceRoot}/src/index.ts” – so it points to our main file
  • set sourceMaps to true – so it can use *.map.js files generated by TypeScript compiler
  • set outDir to “${workspaceRoot}/src” – so it can find where map files are located

then save the file and switch to debugger view using left-side toolbar button. To start debugging, hit green arrow button.

Development in console without IDE

As we installed standalone TypeScript compiler, we can develop our project even without VS Code. To do that, being in project root folder, start TypeScript compiler

As we enabled watch mode in our tsconfig.json file it will keep running and continuously monitoring source files, recompiling them when required.

Open another console window and use editor of your choice (for example vim) to modify and create project files

We can run our project from console

The output should be

I hope at this point you have a functional project same as I do. If you got any problems or want to know more about any of the related matters, please leave a comment below.


You can grab source of this project on GitHub – you will have to run  npm install and typings install  in project folder to install dependencies and ambient definitions.

Share This

Share This

Share this post with your friends!