Configuring TypeScript Compilation

TypeScript uses the file tsconfig.json to adjust project compile options

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
"compilerOptions": {
  "module": "commonjs",
  "target": "es6",
  "noImplicityAny": true,
  "moduleResolution": "node",
  "sourceMap": true,
  "outDir": "dist",
  "baseUrl": ".",
  "paths": {
    "*": [
      "node_modules/*",
      "src/types/*"
    ]
  }
}
compilerOptions Description
“module”: “commonjs” The output module type (in your .js files). Node uses commonjs
“target”: “es6” The output language level. Node supports ES6
“noImplicityAny”: true Enables a stricter setting which throws errors when something has a default any value
“moduleResolution”: “node” TypeScript attempts to mimic Node’s module resolution strategy
“sourceMap”: true
“ourDir”: “dist” Location to output .js files after compilation
“baseUrl”: “.” Part of configuring module resolution
“paths”: {…} Part of configuring module resolution

The rest of the file define the TypeScript project context. The project context is basically a set of options that determine which files are compiled when the compiler is invoked with a specific tsconfig.json.

1
2
3
"include": [
  "src/**/*"
]

include takes an array of glob pattern of files to include in the compilation.

Type Definition (.d.ts) Files

TypeScript uses .d.ts files to provide types for JavaScript libraries that were not written in TypeScript. This is great because once you have a .d.ts file, TypeScript can type check that library and provide you better help in your editor. The TypeScript community actively shares all the most up-to-date .d.ts files for popular libraries on a Github repository called DefinitelyTyped.

Because the "noImplicityAny": true, we are required to have a .d.ts file for every library used. You could set noImplicityAny to false to silence errors about missing .d.ts files. It’s a best practice to have a .d.ts file for every library(Even the .d.ts file is basically empty)

Installing .d.ts files from DefinitelyTyped

For the most part, you’ll find d.ts files for the libraries you are using on DefinitelyTyped. These .d.ts files can be easily installed into your project by using npm scope @types. For example, if we want the .d.ts file for jQuery, we can do so with npm install --save-dev @types/jquery.

Once .d.ts files have been installed using npm, you should see them in your node_modules/@types folder. The compiler will always look in this folder for .d.ts files when resolving JavaScript libraries.

What if a library isn’t on DefinitelyTyped?

Setting up TypeScript to look for .d.ts files in another folder

The Compiler knows to look in node_modules/@types by default, but to help the compiler find our own .d.ts files we have to configure path mapping in our tsconfig.json. Path mapping can get pretty confusing, but the basic idea is that the TypeScript compiler will look in specific places, in a specific order when resolving modules, and we have the ability to tell the compiler exactly how to do it. In the tsconfig.json for this project you’ll see the following:

1
2
3
4
5
6
"baseUrl": ".",
"paths": {
  "*": [
    "src/types/*"
  ]
}

This tells the TypeScript compiler that in addition to looking in node_module/@types for every import (*) also look in our own .d.ts file location <baseUrl> + src/types/*

First the compiler will look for a .d.ts file in node_modules/@types and then src/types

Summary of .d.ts management

In general if you stick to the following steps you should have minimal .d.ts issues:

  • After installing any npm package as a dependency or dev dependency, immediately try to install the .d.ts file via @types

  • If the library has a .d.ts file on DefinitelyTyped, the install wil succeed and you are done, if the install fails because the package doesn’t exist, generate .d.ts by yourself

Source Map

In the tsconfig.json

1
2
3
"compilerOptiosn": {
  "sourceMaps": true
}

With this option enabled, next to every .js file that the TypeScript compiler outputs there will be a .map.js file as well. This .map.js file provides the information necessary to map back to the source .ts file while debugging.

Using Debugger in VS Code

When debugging in VS Code, it looks for a top level .vscode folder with a launch.json file. In this file, you can tell VS Code exactly what you want to do:

1
2
3
4
5
6
7
8
9
10
11
{
  "type": "node",
  "request": "launch",
  "name": "Debug",
  "program": "${workspaceRoot}/dist/server.js",
  "smartStep": true,
  "outFiles": [
    "../dist/**/*.js"
  ],
  "protocal": "inspector"
}

This is mostly identical to the “Node.js: Launch Program” template with a couple minor changes:

launch.json Options Description
“program”: “${workspaceRoot}/dist/server.js” Modified to point to our entry point in dist
“smartStep”: true Won’t step into code that doesn’t have a source map
“outFiles”: […] Specify where output files a dropped. Use with source map
“protocal”: “inspector” Use the new Node Debug Protocal because we’re on the latest node