How to setup a simple Node.js project with TypeScript support in Intellij IDEA / WebStorm

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.

Intellij IDEA / WebStorm project setup

Intellij IDEA is undoubtedly the best integrated development framework for number of programming languages: Java, JavaScript, TypeScript, Kotlin and many others. It’s a commercial tool, but I must say, it worth every penny. In case if you are only planning to do Node.js / JavaScript / TypeScript development, you can save some money by getting WebStorm, which is basically, stripped off and cheaper version of IDEA for Web development.

You can get a free trial license for a fully functional IDEA Ultimate for 1 month or, if you qualify, you can get discounted or even free license – for educational purposes or for working on Open source projects.

We will start by importing our project (All screenshots taken from Intellij IDEA Ultimate 2016.1 on Mac OS)

Intellij IDEA - creating TypeScript project

Intellij IDEA – creating TypeScript project

then select the folder we have just created

Intellij IDEA - selecting project directory

Intellij IDEA – selecting project directory

In the following project creation wizard just press “Next” button several times leaving all default options and then press “Finish”.

After project loads, we need to enable TypeScript support in project “Preferences” dialog. Make sure “Use tsconfig.json” option is enabled.

Intellij IDEA - enabling TypeScript

Intellij IDEA – enabling TypeScript

As we want to use interactive debugging for TypeScript files, we need to enable map files generation in tsconfig.json

Now, all preparations are done, it is time to start our coding exercise – create file – src/index.ts

Intellij IDEA - creating index.ts

Intellij IDEA – creating index.ts

First thing we were going to do – to read input data from file. We will use Node.js built-in module – fs.

Intellij IDEA - module "fs" not recognised

Intellij IDEA – module “fs” not recognised

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

Intellij IDEA - typings installed

Intellij IDEA – typings installed

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

This module has built-in TypeScript definitions, so we don’t need to use typings util this time.

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

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

At this point our project is completed.

Intellij IDEA - final project structure

Intellij IDEA – final project structure

Running with Node.js

To create “Run” configuration, right-click on index.js file and select “Create index.js …” option from drop-down menu. Then in dialog, make sure “Working directory” is set to the root directory of the project and “JavaScript file” is set to src/index.js

Intellij IDEA - create run configuration

Intellij IDEA – create run configuration

then hit “OK” button and you are ready to go. You can run / debug project in IDEA or just run it in the 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!