tsconfig deep dive

Files and include

A tsconfig file answers two questions at once: which files belong to the project and which rules apply to them. The include list names the source folders, while exclude keeps generated output out.

Start strict about scope. One source folder in and the output folder out covers most small projects.

{ "include": ["src"], "exclude": ["dist"], "compilerOptions": { "strict": true } }

Target vs lib

Target sets the age of the JavaScript that tsc emits. A modern target keeps classes and async code almost untouched, while an older target rewrites them into longer compatible forms.

Lib lists the built in APIs the checker may assume, such as DOM or ES2020 helpers. Match lib to the runtimes where the code will actually run.

{ "compilerOptions": { "target": "ES2020", "lib": ["ES2020", "DOM"] } }

Module systems

Module picks the import and export format of the emitted files. Browsers and bundlers prefer ESNext style imports, while plain Node scripts often still consume CommonJS output.

Pick the format your runner understands first, then let bundlers translate from there. Changing it later rewrites every emitted file.

{ "compilerOptions": { "module": "ESNext", "moduleResolution": "Bundler" } }

Paths and baseUrl

Deep relative imports are hard to read and brittle to move. BaseUrl plus paths defines short aliases so an import always starts from a known root.

Keep the alias map tiny. One or two aliases remove most dot heavy imports without hiding the folder structure.

{ "compilerOptions": { "baseUrl": ".", "paths": { "@app": ["app"], "@utils": ["utils"] } } }

Next: Strict mode

Article author: Arthur Isaev