tsconfig | the missing docs

StackChief LLC
February 06, 2020
0

The tsconfig.json file specifies configuration for a TypeScript project.

The directory you place the tsconfig.json file in is considered the root directory of the TypeScript project by default.

Here is an example of a tsconfig.json file...

{
  "compilerOptions": {
    "compilerOptions": {
      "module": "commonjs",
      "noImplicitAny": true,
      "target": "es6",
      "baseUrl": "./",
      "rootDir": "./",
      "outDir": "dist/",
      "removeComments": true,
      "lib": ["es6", "dom", "es2017"],
      "preserveConstEnums": true,
      "sourceMap": true
    },

    "files":[
      "src/file3.ts"
    ],

    "include": [
      "./src/"
    ],
    "exclude": [
      "./src/file2.ts",
      "./src/file3.ts"
    ]
  }

tsconfig include

The include property specifies the files to be included in the TypeScript project. You can either include files or file paths like ./src/** to specify what should be included.

tsconfig exclude

The exclude property specifies the files to be excluded in the TypeScript project. Any files or file patterns listed here will override things listed in include.

tsconfig files

The files property specifies a list of files to be included. This property requires specific file names and does not support pattern matching.

The files property will override exclude.

Remember that...

1. files overrides exclude

2. exclude overrides include

3. any files referenced within the files you specify in files / include will also be included.

In our example, file1.ts and file3.ts will be included but file2.ts will be ignored by the compiler.

Every relative path in the tsconfig.json file will be resolved relative to the directory the file is in. The files property takes a list of relative or absolute paths such as src/file3.ts". The include and exclude properties take a list of glob-like file patterns such as src/**/*.

tsconfig paths

Using the optional paths compiler option, you can specify how TypeScript resolves certain paths. You can map paths to aliases and then reference those directly from your files.

"paths": {
  "mylibs/*": ["./src/libs/custom/utils/helpers/functions/*"]
}

By specifying a path like this, we can avoid having to reference long relative paths when importing modules....

import { myFunc } from "mylibs/math"

instead of...

import { myFunc } from "../libs/custom/utils/helpers/functions/math"

Note that this requires baseUrl to be specified otherwise errors will be thrown.

tsconfig paths not working?

If things aren't working, be sure that the new path you are defining correctly maps to the files you want to reference by way of glob file pattern matching. For example, mylibs/* works because we correctly match with /*.

Also remember that baseUrl is required with paths.

tsconfig target

The target compiler option specifies the ECMAScript target version that everything will compile to.

For example, if you specify the target as es5 then your output won't have arrow functions. If you specify a target of es6 then your output will have arrow functions.

You can optionally specify this property. By default, the target version is ES3.

In our example, we've specified the target version of es6. You can also specify esnext to get the latest stable version.

tsconfig lib

The lib compiler option specifies the set of type definitions to include in the project.

This property is optional as TypeScript includes a set of definitions by default. Based on your needs you may not need to modify or include this property.

In our example we've set this to ["es6", "dom", "es2017"]. This means we've included the API declarations for ES6, DOM (window, document, etc), and additional APIs available in es2017 (Object.entries, Object.values, Atomics, etc).

By default, TypeScript includes DOM, ES5, and ScriptHost for --target ES5 and DOM, ES6, ScriptHost, and DOM.Iterable for --target ES6.

tsconfig baseurl

The baseUrl compiler option tells TypeScript where to find modules. While relative imports are relative to the importing file, non-relative imports will be resolved relative to the baseUrl property.

In our example, we've specified "./". This means TypeScript will look for files starting in the same folder as the tsconfig.json.

All module imports with non-relative names are assumed to be relative to the baseUrl.

tsconfig outdir

The outDir compiler option specifies the location for the compiled output. When you compile the TypeScript project, the corresponding output will be placed inside the dist/ folder.

If you don't specify the outDir then all of your output will be placed inside the same directories as the corresponding source TypeScript files.

tsconfig rootdir

The rootDir compiler option gives you more control over the output structure of your compiled TypeScript.

In our example, we've specified "./" as the root directory. This tells the compiler to include src/ at the root of the compiled output in the dist/ folder.

This property is optional. If we don't include, the compiler will keep the same output structure but without the src/ at the root.

This option has no influence on what gets included/excluded by the compiler.

tsconfig allowJs

The allowJs compiler option optionally allows you to import regular javascript files. When set to true, the compiler will recognize imports from regular .js files. Otherwise it will throw errors...

Comment