Troubleshooting Handbook: tsconfig.json

You can find all the Compiler options in the TypeScript docs. The new TS docs also has per-flag annotations of what each does. This is the setup I roll with for APPS (not libraries - for libraries you may wish to see the settings we use in tsdx):

"compilerOptions": {
"incremental": true,
"outDir": "build/lib",
"target": "es5",
"module": "esnext",
"lib": ["dom", "esnext"],
"sourceMap": true,
"importHelpers": true,
"declaration": true,
"rootDir": "src",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"allowJs": false,
"jsx": "react",
"moduleResolution": "node",
"baseUrl": "src",
"forceConsistentCasingInFileNames": true,
"esModuleInterop": true,
"suppressImplicitAnyIndexErrors": true,
"allowSyntheticDefaultImports": true,
"experimentalDecorators": true
"include": ["src/**/*"],
"exclude": ["node_modules", "build", "scripts"]

You can find more recommended TS config here.

Please open an issue and discuss if there are better recommended choices for React.

Selected flags and why we like them:

  • esModuleInterop: disables namespace imports (import * as foo from "foo") and enables CJS/AMD/UMD style imports (import fs from "fs")
  • strict: strictPropertyInitialization forces you to initialize class properties or explicitly declare that they can be undefined. You can opt out of this with a definite assignment assertion.
  • "typeRoots": ["./typings", "./node_modules/@types"]: By default, TypeScript looks in node_modules/@types and parent folders for third party type declarations. You may wish to override this default resolution so you can put all your global type declarations in a special typings folder.

Compilation speed grows linearly with size of codebase. For large projects, you will want to use Project References. See our ADVANCED cheatsheet for commentary.