I'm a huge TypeScript fan. I prefer to write each new project in it, rather than in pure JavaScript. In this article, I will not discuss the reasons for choosing TypeScript or its advantages and disadvantages. I want this post to serve as a kind of cheat sheet for anyone who wants to understand how to customize tsconfig
, sort out its many flags, and maybe learn some useful tricks.
So, in this article, I want to provide a revised and ordered squeeze of the documentation, which, I am sure, will be useful to those who are just starting their journey in the TypeScript world or to those who, until now, have not found the time and energy to figure out the details and now wants to close this gap.
If you open the official reference tsconfig
, then there will be a complete list of all settings, divided by groups. However, this does not give an understanding of where to start and what is required from this extensive list of options, and what can be ignored (at least for the time being). Plus, sometimes options are grouped according to some technical rather than logical meaning. For example, some check flags can be found in a group Strict Checks
, some in Linter Checks
, and others in Advanced
. This is not always easy to understand.
All options, as well as the article itself, I divided into two groups - basic and "checks". In the first part of the article, we will talk about basic settings, and in the second, about various checks, that is, about tuning the compiler's strictness.
Tsconfig structure
Let's consider the structure and some features of the config.
tsconfig.json
consists of two parts. Some options must be specified inroot
, and some incompilerOptions
tsconfig.json
supports comments. IDEs like WebStorm and Visual Studio Code are aware of this and do not highlight comments as syntax errors
tsconfig.json
supports inheritance. Options can be divided according to some principle, described in different files and combined using a special directive
This is our disc tsconfig.json
:
{
// extends
// tsconfig-checks.json
"extends": "./tsconfig-checks.json",
// project-specific
"compilerOptions": {
// ,
}
}
root
: extends
, files
, include
, exclude
, references
, typeAcquisition
. 4. compilerOptions
.
root
compileOnSave
ts-node
. IDE .
root
extends
Type: string | false, default: false.
. , . , . , , . , tsconfig.json
:
{
"compilerOptions": {
//
//
}
}
use-case, . production development . tsconfig-dev.json
:
{
"extends": "./tsconfig.json",
"compilerOptions": {
// , dev
"sourceMap": true,
"watch": true
}
}
, extends
. , . . , .
. , tsc --showConfig
.
files
Type: string[] | false, default: false, include
.
.
{
"compilerOptions": {},
"files": [
"core.ts",
"app.ts"
]
}
.
include
Type string[], default: files
, exclude
.
files
, TypeScript . include
, ["**/*"]
. , . , . , .
{
"compilerOptions": {},
"include": [
"src/**/*",
"tests/**/*"
]
}
, TypeScript .ts
, .tsx
.d.ts
. allowJs
, .js
.jsx
.
src
, ./src
, src/**/*
. ./src
.
, include
exclude
, TypeScript files
. tsc --showConfig
.
exclude
Type: string[], default: ["node_modules", "bower_components", "jspm_packages"].
, , include
. , npm
, bower
jspm
, . , TypeScript outDir
, . , . , . , . . , .
{
"compilerOptions": {},
"exclude": [
"node_modules",
"./src/**/*.spec.ts"
]
}
exclude
, files
.
exclude
, , .
compilerOptions
target
Type: string, default: ES3
, lib
, module
.
ECMAScript, . : ES3
, ES5
, ES6
( ES2015
), ES2016
, ES2017
, ES2018
, ES2019
, ES2020
, ESNext
. backend / ES6
, Node.js
ES5
, . ES6
, , 97.29% . frontend .
module
Type: string, default: target
, moduleResolution
.
, . : None
, CommonJS
, AMD
, System
, UMD
, ES6
, ES2015
, ES2020
or ESNext
. backend / ES6
CommonJS
Node.js
, . frontend ES6
. , UMD
.
moduleResolution
Type: string, default: module
.
, . : node
classic
. classic
99% , legacy. , , . module
moduleResolution
classic
.
, node
.
lib
Type: string[], default: target
.
target
, TypeScript (*.d.ts-
) . , target
ES6
, TypeScript array.find
, . target
ES5
, find
, JavaScript. . , , TypeScript , , lib
. , ES2015
, ES2015.Core
( find
, findIndex
. .).
, , .
--target ES5 : DOM, ES5, ScriptHost --target ES6: DOM, ES6, DOM.Iterable, ScriptHost
- lib
. , , DOM
:
{
"compilerOptions": {
"target": "ES5",
"lib": [
"DOM",
"ES2015.Core"
]
}
}
outDir
Type: string, default: .
, . : .js
, .d.ts
, .js.map
. , . .gitignore
. . , .
outDir
:
├── module
│ └── core.js
│ └── core.ts
├── index.js
└── index.ts
outDir
:
├── dist
│ └── module
│ | └── core.js
│ └── index.js
├── module
│ └── core.ts
└── index.ts
outFile
Type: string, default: none.
, . , webpack
… , module
None
, System
, or AMD
. , CommonJS
or ES6
. outFile
. , , .
allowSyntheticDefaultImports
Type: boolean, default: module
esModuleInterop
.
- default import
, ts-loader
babel-loader
. , d.ts-
. , :
//
import * as React from 'react';
//
import React from 'react';
, esModuleInterop
module
=== "system".
esModuleInterop
Type: boolean, default: false.
, CommonJS
ES6
.
// moment CommonJS
// ES6
import Moment from 'moment';
// esModuleInterop undefined
console.log(Moment);
// c [object Object]
console.log(Moment);
allowSyntheticDefaultImports
. .
alwaysStrict
Type: boolean, default: strict
.
strict mode
“use strict”
.
false, strict
, true.
downlevelIteration
Type: boolean, default: false.
ES6
: for / of
, array spread
, arguments spread
. ES5
, for / of
for
:
// es6
const str = 'Hello!';
for (const s of str) {
console.log(s);
}
// es5 downlevelIteration
var str = "Hello!";
for (var _i = 0, str_1 = str; _i < str_1.length; _i++) {
var s = str_1[_i];
console.log(s);
}
, , emoji
. . . , . downlevelIteration
"", . , . , playground target -> es5
, downlevelIteration -> true
.
, , Symbol.iterator
. .
forceConsistentCasingInFileNames
Type: boolean, default: false.
(case-sensitive) . , case-insensitive import FileManager from './FileManager.ts'
, fileManager.ts
, . . TypeScript - .
compilerOptions,
declaration
Type: boolean, default: false.
, JavaScript , -, d.ts
- . js . js
, d.ts
-. , , npm
. , JavaScript, TypeScript.
declarationDir
Type: string, default: none, declaration
.
js
-. d.ts
- .
emitDeclarationOnly
Type: boolean, default: false, declaration
.
- d.ts
-, js
-.
allowJs
Type: boolean, default: false.
JavaScript TypeScript . allowJs
TypeScript ts
, js
. , . , . TypeScript.
checkJs
Type: boolean, default: false, allowJs
.
TypeScript ts
, js
-. JavaScript, TS- jsDoc . , . , jsDoc, .
4.1 checkJs
, allowJs
.
experimentalDecorators emitDecoratorMetadata
Type: boolean, default: false.
experimentalDecorators
, emitDecoratorMetadata
-, .
emitDecoratorMetadata
reflect-metadata.
resolveJsonModule
Type: boolean, default: false.
*.json
. .
// .json
import config from './config.json'
jsx
Type: string, default: none.
React, jsx
. react
react-native
. jsx-
preserve
react-jsx
react-jsxdev
.
, . . .