Skip to main content

Typescript compiler config

This document details best practices for configuring TypeScript compiler settings in your project.

info

The following content is recommended.

Rationale​

The preferred language for all aspects of software engineering is TypeScript. Using a single language for all aspects of software engineering encourages collaboration between engineers and cross-skilling into areas that engineers are less familiar with. This makes the engineering team more flexible and efficient. Typescript is strongly typed and should indicate issues at compile time before they appear at run time

Having a standardized tsconfig.json across multiple repositories ensures consistency and reliability. A common configuration ensures that all projects adhere to the same coding standards and practices, making it easier for engineers to switch between projects without having to learn new configurations.

Description​

The tsconfig.json file is essential for configuring the TypeScript compiler options for your project. It defines the root files and the compiler options required to compile the project.

Example Configuration​

{
  "compilerOptions": {
    "noEmit": true,
    "target": "ES2018",
    "module": "commonjs",
    "lib": ["es2018"],
    "declaration": true,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "inlineSourceMap": true,
    "inlineSources": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": true,
    "allowUnreachableCode": false,
    "allowUnusedLabels": false,
    "typeRoots": ["./node_modules/@types"]
  },
  "exclude": [],
  "include": ["src", "test"]
}

Explanation of Configuration Options​

  • compilerOptions

    • noEmit: Prevents the compiler from emitting output files. Useful when you only want to type-check your code.
    • target: Specifies the target ECMAScript version. ES2018 is chosen for modern JavaScript features.
    • module: Specifies the module system to use. commonjs is chosen for Node.js compatibility.
    • lib: Specifies the library files to include in the compilation. es2018 includes modern JavaScript features.
    • declaration: Generates corresponding .d.ts files for TypeScript files, useful for library projects.
    • strict: Enables all strict type-checking options.
    • noImplicitAny: Raises an error on expressions and declarations with an implied any type.
    • strictNullChecks: Ensures that null and undefined are only assignable to themselves and any.
    • noImplicitThis: Raises an error when this is of type any.
    • alwaysStrict: Ensures that strict mode is always enabled.
    • noUnusedLocals: Raises an error on unused local variables.
    • noUnusedParameters: Raises an error on unused parameters.
    • noImplicitReturns: Ensures that all code paths in a function return a value.
    • noFallthroughCasesInSwitch: Raises an error for fallthrough cases in switch statements.
    • inlineSourceMap: Includes source maps inside the emitted JavaScript files.
    • inlineSources: Includes the original source code in the source maps.
    • experimentalDecorators: Enables experimental support for decorators.
    • strictPropertyInitialization: Ensures that class properties are initialized in the constructor.
    • allowUnreachableCode: Disallows unreachable code.
    • allowUnusedLabels: Disallows unused labels.
    • typeRoots: Specifies the directories in which TypeScript looks for type definitions.

  • exclude Specifies the files and directories to exclude from the compilation.

  • include Specifies the files and directories to include in the compilation.

Best Practices​

Enable Strict Mode​

Always enable strict mode (strict: true) to catch potential errors early and enforce best practices.

Use Modern JavaScript Features​

Set the target to a modern ECMAScript version (e.g., ES2018) to take advantage of the latest JavaScript features.

Generate Declaration Files​

Enable declaration to generate .d.ts files, especially if you are building a library.

Type Checking​

Enable options like noImplicitAny, strictNullChecks, and noImplicitThis to enforce strict type checking.

Error Prevention​

Enable options like noUnusedLocals, noUnusedParameters, noImplicitReturns, and noFallthroughCasesInSwitch to prevent common errors.

Source Maps​

Use inlineSourceMap and inlineSources to include source maps and original source code in the emitted files, which is useful for debugging.

Experimental Features​

Enable experimentalDecorators if you are using decorators in your project.

Property Initialization​

Enable strictPropertyInitialization to ensure that class properties are properly initialized.

Exclude Unnecessary Files​

Use the exclude option to exclude files and directories that should not be part of the compilation.

Include Necessary Files​

Use the include option to specify the files and directories that should be included in the compilation.

References & Further Reading​