Howto: Configure IntelliJ/WebStorm for TypeScript development

Published in

theCodeCampus Knowledge

5 min readOct 7, 2016

JetBrain’s IDEs (IntelliJ, WebStorm, …) started to support the TypeScript language quite early and are definitely among the most popular IDEs available. However, correctly configuring them for TypeScript development can be quite challenging and frustrating. Invalid error messages and a sluggish experience are common problems. In this post I want to share my experience and best practice. However, some (or all) of these information might become obsolete due to IDE or TypeScript updates.

I will use the name IntelliJ representativly for all JetBrain’s IDE in this article. They all have the same TypeScript support.

IDE Settings

First you need to configure IntelliJ’s TypeScript plugin:

File -> Settings
Languages & Frameworks -> TypeScript

Node Interpreter

Choose the Node interpreter to use.

TypeScript Version

The default value is “1.8.10 (bundled)”. I recommend to always switch to the version you actually use. If you installed TypeScript with npm you simply can select the node_modules/typescript/lib folder in your project:

Use TypeScript Service (Experimental)

Even though it is marked as experimental, you should turn this option on. So far I never experienced any problems with this. When this option is turned on, IntelliJ will use the TypeScript internal language service (which is used in e.g. Visual Studio Code) for code validation and error messages.

(NOT) Enable TypeScript Compiler

For small projects or while still learning TypeScript, it is useful to let IntelliJ compile and generate the .js files. In “normal” projects you should use a tool like WebPack/grunt/gulp. Hence, leave this option off and use a proper build pipeline.

tsconfig.json

The tsconfig.json file is a “standardized” file used to configure the TypeScript compiler settings. Additionally, the presence of this file usually marks a project as a TypeScript project. While you might be able to write TypeScript code in IntelliJ without this file, it is definitely not recommended. You should always have one!

Where to place the tsconfig.json

Option A) root folder

Most people put the tsconfig.json file in the root folder of the project. A typical web project might look like this:

/package.json
/tsconfig.json
/src/code1.ts
/src/code2.ts
/src/...
/node_modules/...
/output/...

Keep in mind that this marks the whole project as relevant to the compiler! If you are not careful, other tools in you build pipeline might pick up too many files and incorrectly try to compile every file in e.g. the node_modules folder. You have to use the include/exclude/rootDir/… properties to correctly define the project scope. If you use a build tool like Webpack, gulp or grunt, you might not need to specify the scope however, since these tools provide their own mechanism (e.g. gulp.src) to specify the input files.

Nevertheless, placing the tsconfig.json in the root folder sometimes seems to cause problems (e.g. sluggish IDE). So it’s best to always define your scope with the configuration properties.

Option B) src folder (don’t)

To be less fault-prone to configuration errors, you can put the tsconfig.json in the src folder of the application. The setup would look like this:

/package.json
/src/tsconfig.json
/src/code1.ts
/src/code2.ts
/src/...
/node_modules/...
/output/...

This way we can be sure that only our source files are relevant to the compiler. I used to apply option B but after the TypeScript 2.0 release I adopted option A (see below).

Include typings

tsconfig.json

You need to make sure that you include your typings folder as well, if you specify your scope explicitly using rootDir/include/etc. E.g.:

file: /app/tsconfig.json{
  "compilerOptions": {
      .... 
  },
  "include": [
    "src/**/*",
    "typings/**/*" // <-- don't forget this line!
  ]
}

If you put the tsconfig.json in the src folder, you have two options:

a) Use “..” to navigate to the parent project folder to specify the typings folder:

file: /app/tsconfig.json{
  "compilerOptions": {
      .... 
  },
  "include": [
    "**/*",
    "../typings/**/*"  // <-- the ".." trick
  ]
}

b) definition file: All .d.ts files within the src folder will be used by the compiler. You can create a simple definition file that only references the main typings file:

file: /src/typings.d.ts/// <reference path="../typings/index.d.ts" />

Typings with @ types (npm scope)

Above I wrote that you should place the tsconfig.json file in the root folder if you use TypeScript 2.0. The reason for this the introduced typings lookup in the “@ types” scope.

The idea is that instead of using tsd/typings, you use npm to install the definition files. Additionally, authors of these definition files and the TypeScript compiler agree on using the “@ types” scope. So when you write

import * as _ from "lodash";

the TypeScript compiler will look in “node_modules/@types/lodash/” for definition files.

The problem with the current IntelliJ release is however, that even if you configured IntelliJ to use the “TypeScript Service”, you won’t be able to get the “navigate to”/”show parameter”/etc. support, if you place your tsonfig.json in the src folder. It will look like this:

While placing tsconfig.json in the root folder works fine:

I know, this doesn’t make sense, but please don’t kill the messenger!

Summary

I hope these steps help you to use TypeScript with IntelliJ. Other IDEs like Visual Studio Code and Atom have fantastic support for TypeScript as well (sometimes even better), but overall I still think that IntelliJ is the better IDE.

Please feel free to add a comment if I missed something. I will try to update this article or post an updated article.