A TypeScript 6 tsconfig.json with all options organised by category, documentation comments & explanations, and defaults applied

tsconfig.json

{
  // Visit https://aka.ms/tsconfig to read more about this file
  "$schema": "https://json.schemastore.org/tsconfig",
  // If no 'files' or 'include' property is present in a tsconfig.json, the compiler defaults to including all files in the containing directory and subdirectories except those specified by 'exclude'. When a 'files' property is specified, only those files and those specified by 'include' are included.
  // "files": [],
  // Path to base configuration file to inherit from..
  // "extends": [],
  // Specifies a list of glob patterns that match files to be included in compilation.
  // "include": [],
  // Specifies a list of files to be excluded from compilation.
  // "exclude": [],
  // Project references are a way to structure your TypeScript programs into smaller pieces. Using Project References can greatly improve build and editor interaction times, enforce logical separation between components, and organize your code in new and improved ways.
  // "references": [],
  // Instructs the TypeScript compiler how to compile .ts files.
  "compilerOptions": {
    /*
     * ------------------------------------------------------
     * CATEGORY: Type Checking
     * ------------------------------------------------------
     */
    // When: undefined (default) provide suggestions as warnings to editors, true unreachable code is ignored, false raises compiler errors about unreachable code. These warnings are only about code which is provably unreachable due to the use of JavaScript syntax
    // "allowUnreachableCode": null,
    // When: undefined (default) provide suggestions as warnings to editors, true unused labels are ignored, false raises compiler errors about unused labels. Labels are very rare in JavaScript and typically indicate an attempt to write an object literal
    // "allowUnusedLabels": null,
    // Ensures that your files are parsed in the ECMAScript strict mode, and emit "use strict" for each source file
    // "alwaysStrict": false,
    // With exactOptionalPropertyTypes enabled, TypeScript applies stricter rules around how it handles properties on type or interfaces which have a ? prefix
    "exactOptionalPropertyTypes": true,
    // Report errors for fallthrough cases in switch statements. Ensures that any non-empty case inside a switch statement includes either break, return, or throw. This means you won't accidentally ship a case fallthrough bug
    // "noFallthroughCasesInSwitch": false,
    // In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable when it cannot infer the type
    // "noImplicitAny": false,
    // When working with classes which use inheritance, it's possible for a sub-class to get "out of sync" with the functions it overloads when they are renamed in the base class
    // "noImplicitOverride": false,
    // When enabled, TypeScript will check all code paths in a function to ensure they return a value
    // "noImplicitReturns": false,
    // Raise error on 'this' expressions with an implied 'any' type
    // "noImplicitThis": false,
    // This setting ensures consistency between accessing a field via the "dot" (obj.key) syntax, and "indexed" (obj["key"]) and the way which the property is declared in the type
    // "noPropertyAccessFromIndexSignature": false,
    // TypeScript has a way to describe objects which have unknown keys but known values on an object, via index signatures. Turning on noUncheckedIndexedAccess will add undefined to any un-declared field in the type
    "noUncheckedIndexedAccess": true,
    // Report errors on unused local variables
    // "noUnusedLocals": false,
    // Report errors on unused parameters in functions
    // "noUnusedParameters": false,
    // The strict flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness. Turning this on is equivalent to enabling all of the strict mode family options, which are outlined below. You can then turn off individual strict mode family checks as needed
    "strict": true,
    // When set, TypeScript will check that the built-in methods of functions call, bind, and apply are invoked with correct argument for the underlying function
    // "strictBindCallApply": false,
    // Built-in iterators are instantiated with a TReturn type of undefined instead of any
    // "strictBuiltinIteratorReturn": false,
    // When enabled, this flag causes functions parameters to be checked more correctly
    // "strictFunctionTypes": false,
    // When strictNullChecks is false, null and undefined are effectively ignored by the language. This can lead to unexpected errors at runtime. When strictNullChecks is true, null and undefined have their own distinct types and you'll get a type error if you try to use them where a concrete value is expected
    // "strictNullChecks": false,
    // When set to true, TypeScript will raise an error when a class property was declared but not set in the constructor
    // "strictPropertyInitialization": false,
    // In TypeScript 4.0, support was added to allow changing the type of the variable in a catch clause from any to unknown
    // "useUnknownInCatchVariables": false,
    /*
     * ------------------------------------------------------
     * CATEGORY: Modules
     * ------------------------------------------------------
     */
    // In TypeScript 5.0, when an import path ends in an extension that isn't a known JavaScript or TypeScript file extension, the compiler will look for a declaration file for that path in the form of {file basename}.d.{extension}.ts
    // "allowArbitraryExtensions": false,
    // --allowImportingTsExtensions allows TypeScript files to import each other with a TypeScript-specific extension like .ts, .mts, or .tsx. This flag is only allowed when --noEmit or --emitDeclarationOnly is enabled, since these import paths would not be resolvable at runtime in JavaScript output files
    // "allowImportingTsExtensions": false,
    // When set to true, allowUmdGlobalAccess lets you access UMD exports as globals from inside module files. A module file is a file that has imports and/or exports. Without this flag, using an export from a UMD module requires an import declaration
    // "allowUmdGlobalAccess": false,
    // Sets a base directory from which to resolve bare specifier module names
    // "baseUrl": "",
    // --customConditions takes a list of additional conditions that should succeed when TypeScript resolves from an exports or imports field of a package.json. These conditions are added to whatever existing conditions a resolver will use by default
    // "customConditions": [],
    // Sets the module system for the program. See the theory behind TypeScript's module option and its reference page for more information. You very likely want "nodenext" for modern Node.js projects and preserve or esnext for code that will be bundled
    "module": "nodenext",
    // Specify the module resolution strategy
    // "moduleResolution": "node10",
    // Provides a way to override the default list of file name suffixes to search when resolving a module
    // "moduleSuffixes": [],
    // By default, TypeScript will examine the initial set of files for import and <reference directives and add these resolved files to your program. If noResolve is set, this process doesn't happen
    // "noResolve": false,
    // When --noUncheckedSideEffectImports is enabled, TypeScript will error if it can't find a source file for a side effect import
    "noUncheckedSideEffectImports": true,
    // A series of entries which re-map imports to lookup locations relative to the baseUrl if set, or to the tsconfig file itself otherwise
    // "paths": {},
    // Allows importing modules with a .json extension, which is a common practice in node projects. This includes generating a type for the import based on the static JSON shape
    // "resolveJsonModule": false,
    // --resolvePackageJsonExports forces TypeScript to consult the exports field of package.json files if it ever reads from a package in node_modules
    // "resolvePackageJsonExports": false,
    // --resolvePackageJsonImports forces TypeScript to consult the imports field of package.json files when performing a lookup that starts with # from a file whose ancestor directory contains a package.json
    // "resolvePackageJsonImports": false,
    // Rewrite .ts, .tsx, .mts, and .cts file extensions in relative import paths to their JavaScript equivalent in output files
    // "rewriteRelativeImportExtensions": false,
    // When TypeScript compiles files, it keeps the same directory structure in the output directory as exists in the input directory
    // "rootDir": "",
    // Using rootDirs, you can inform the compiler that there are many "virtual" directories acting as a single root. This allows the compiler to resolve relative module imports within these "virtual" directories, as if they were merged in to one directory
    // "rootDirs": [],
    // By default all visible "@types" packages are included in your compilation. If typeRoots is specified, only packages under typeRoots will be included
    // "typeRoots": [],
    // By default all visible "@types" packages are included in your compilation. If types is specified, only packages listed will be included in the global scope
    "types": [],
    /*
     * ------------------------------------------------------
     * CATEGORY: Emit
     * ------------------------------------------------------
     */
    // Generate .d.ts files for every TypeScript or JavaScript file inside your project. These .d.ts files are type definition files which describe the external API of your module
    "declaration": true,
    // Offers a way to configure the root directory for where declaration files are emitted
    // "declarationDir": "",
    // Generates a source map for .d.ts files which map back to the original .ts source file. This will allow editors such as VS Code to go to the original .ts file when using features like Go to Definition
    "declarationMap": true,
    // Downleveling is TypeScript's term for transpiling to an older version of JavaScript. This flag is to enable support for a more accurate implementation of how modern JavaScript iterates through new concepts in older JavaScript runtimes
    // "downlevelIteration": false,
    // Controls whether TypeScript will emit a byte order mark (BOM) when writing output files. Some runtime environments require a BOM to correctly interpret a JavaScript files; others require that it is not present
    // "emitBOM": false,
    // Only emit .d.ts files; do not emit .js files
    // "emitDeclarationOnly": false,
    // For certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays or objects, and async operations. By default, these helpers are inserted into files which use them. If the importHelpers flag is on, these helper functions are instead imported from the tslib module
    // "importHelpers": false,
    // When set, instead of writing out a .js.map file to provide source maps, TypeScript will embed the source map content in the .js files
    // "inlineSourceMap": false,
    // When set, TypeScript will include the original content of the .ts file as an embedded string in the source map (using the source map's sourcesContent property). This is often useful in the same cases as inlineSourceMap
    // "inlineSources": false,
    // Specify the location where debugger should locate map files instead of generated locations
    // "mapRoot": "",
    // Specify the end of line sequence to be used when emitting files: 'CRLF' (dos) or 'LF' (unix)
    // "newLine": "lf",
    // Do not emit compiler output files like JavaScript source code, source-maps or declarations. This makes room for another tool like Babel, or swc to handle converting the TypeScript file to a file which can run inside a JavaScript environment
    // "noEmit": false,
    // Instead of importing helpers with importHelpers, you can provide implementations in the global scope for the helpers you use and completely turn off emitting of helper functions
    // "noEmitHelpers": false,
    // Do not emit compiler output files like JavaScript source code, source-maps or declarations if any errors were reported
    // "noEmitOnError": false,
    // If specified, .js (as well as .d.ts, .js.map, etc.) files will be emitted into this directory. The directory structure of the original source files is preserved
    // "outDir": "",
    // If specified, all global (non-module) files will be concatenated into the single output file specified
    // "outFile": "",
    // Do not erase const enum declarations in generated code. const enums provide a way to reduce the overall memory footprint of your application at runtime by emitting the enum value instead of a reference
    // "preserveConstEnums": false,
    // Strips all comments from TypeScript files when converting into JavaScript
    // "removeComments": false,
    // Enables the generation of sourcemap files. These files allow debuggers and other tools to display the original TypeScript source code when actually working with the emitted JavaScript files
    "sourceMap": true,
    // Specify the location where a debugger should locate TypeScript files instead of relative source locations
    // "sourceRoot": "",
    // Do not emit declarations for code that has an @internal annotation in its JSDoc comment. This is an internal compiler option; use at your own risk, because the compiler does not check that the result is valid
    // "stripInternal": false,
    /*
     * ------------------------------------------------------
     * CATEGORY: JavaScript Support
     * ------------------------------------------------------
     */
    // Allow JavaScript files to be imported inside your project, instead of just .ts and .tsx files
    // "allowJs": false,
    // Works in tandem with allowJs. When checkJs is enabled then errors are reported in JavaScript files. This is the equivalent of including // @ts-check at the top of all JavaScript files which are included in your project
    // "checkJs": false,
    // The maximum dependency depth to search under node_modules and load JavaScript files. This flag can only be used when allowJs is enabled, and is used if you want to have TypeScript infer types for all of the JavaScript inside your node_modules
    // "maxNodeModuleJsDepth": 0,
    /*
     * ------------------------------------------------------
     * CATEGORY: Editor Support
     * ------------------------------------------------------
     */
    // To avoid a possible memory bloat issues when working with very large JavaScript projects, there is an upper limit to the amount of memory TypeScript will allocate. Turning this flag on will remove the limit
    // "disableSizeLimit": false,
    // List of language service plugins to run inside the editor. Language service plugins are a way to provide additional information to a user based on existing TypeScript files
    // "plugins": [],
    /*
     * ------------------------------------------------------
     * CATEGORY: Interop Constraints
     * ------------------------------------------------------
     */
    // When set to true, allowSyntheticDefaultImports allows you to write an import like: import React from "react" instead of: import * as React from "react" when the module does not explicitly specify a default export
    // "allowSyntheticDefaultImports": false,
    // Node.js supports running TypeScript files directly as of v23.6; however, only TypeScript-specific syntax that does not have runtime semantics are supported under this mode. In other words, it must be possible to easily erase any TypeScript-specific syntax from a file, leaving behind a valid JavaScript file
    // "erasableSyntaxOnly": false,
    // By default (with esModuleInterop false or not set) TypeScript treats CommonJS/AMD/UMD modules similar to ES6 modules. Turning on esModuleInterop will fix both of these problems in the code transpiled by TypeScript
    // "esModuleInterop": false,
    // TypeScript follows the case sensitivity rules of the file system it's running on. This can be problematic if some developers are working in a case-sensitive file system and others aren't. When this option is set, TypeScript will issue an error if a program tries to include a file by a casing different from the casing on disk
    // "forceConsistentCasingInFileNames": true,
    // Require sufficient annotation on exports so other tools can trivially generate declaration files
    // "isolatedDeclarations": false,
    // While you can use TypeScript to produce JavaScript code from TypeScript code, it's also common to use other transpilers such as Babel to do this. However, other transpilers only operate on a single file at a time, which means they can't apply code transforms that depend on understanding the full type system. Setting the isolatedModules flag tells TypeScript to warn you if you write certain code that can't be correctly interpreted by a single-file transpilation process
    "isolatedModules": true,
    // This is to reflect the same flag in Node.js; which does not resolve the real path of symlinks
    // "preserveSymlinks": false,
    // By default, TypeScript does something called import elision. The verbatimModuleSyntax flag simplifies the situation. The rules are much simpler - any imports or exports without a type modifier are left around. Anything that uses the type modifier is dropped entirely
    "verbatimModuleSyntax": true,
    /*
     * ------------------------------------------------------
     * CATEGORY: Backwards Compatibility
     * ------------------------------------------------------
     */
    // In prior versions of TypeScript, this controlled what encoding was used when reading text files from disk. Today, TypeScript assumes UTF-8 encoding, but will correctly detect UTF-16 (BE and LE) or UTF-8 BOMs
    // "charset": "utf8",
    // Deprecated in favor of verbatimModuleSyntax. This flag controls how import works, there are 3 different options: remove, preserve, error
    // "importsNotUsedAsValues": "remove",
    // This flag changes the keyof type operator to return string instead of string | number when applied to a type with a string index signature
    // "keyofStringsOnly": false,
    // You shouldn't need this. By default, when emitting a module file to a non-ES6 target, TypeScript emits a "use strict"; prologue at the top of the file. This setting disables the prologue
    // "noImplicitUseStrict": false,
    // TypeScript will unify type parameters when comparing two generic functions. This flag can be used to remove that check
    // "noStrictGenericChecks": false,
    // Use outFile instead. The out option computes the final file location in a way that is not predictable or consistent. This option is retained for backward compatibility only and is deprecated
    // "out": "",
    // Deprecated in favor of verbatimModuleSyntax. There are some cases where TypeScript can't detect that you're using an import. preserveValueImports will prevent TypeScript from removing the import, even if it appears unused
    // "preserveValueImports": false,
    // This disables reporting of excess property errors
    // "suppressExcessPropertyErrors": false,
    // Turning suppressImplicitAnyIndexErrors on suppresses reporting the error about implicit anys when indexing into objects
    // "suppressImplicitAnyIndexErrors": false,
    /*
     * ------------------------------------------------------
     * CATEGORY: Language and Environment
     * ------------------------------------------------------
     */
    // Enables experimental support for emitting type metadata for decorators which works with the module reflect-metadata
    // "emitDecoratorMetadata": false,
    // Enables experimental support for decorators, which is a version of decorators that predates the TC39 standardization process
    // "experimentalDecorators": false,
    // Controls how JSX constructs are emitted in JavaScript files. This only affects output of JS files that started in .tsx files
    "jsx": "react-jsx",
    // Changes the function called in .js files when compiling JSX Elements using the classic JSX runtime. The most common change is to use "h" or "preact.h" instead of the default "React.createElement" if using preact
    // "jsxFactory": "React.createElement",
    // Specify the JSX fragment factory function to use when targeting react JSX emit with jsxFactory compiler option is specified, e.g. Fragment
    // "jsxFragmentFactory": "React.Fragment",
    // Declares the module specifier to be used for importing the jsx and jsxs factory functions when using jsx as "react-jsx" or "react-jsxdev" which were introduced in TypeScript 4.1
    // "jsxImportSource": "react",
    // TypeScript includes a default set of type definitions for built-in JS APIs (like Math), as well as type definitions for things found in browser environments (like document). TypeScript also includes APIs for newer JS features matching the target you specify
    // "lib": [],
    // TypeScript 4.5 introduced the possibility of substituting the default lib files with custom ones. The --libReplacement flag allows you to disable this behavior
    // "libReplacement": false,
    // This setting controls how TypeScript determines whether a file is a script or a module. There are three choices: "auto" (default), "legacy", and "force"
    "moduleDetection": "force",
    // Disables the automatic inclusion of any library files. If this option is set, lib is ignored
    // "noLib": false,
    // Use jsxFactory instead. Specify the object invoked for createElement when targeting react for TSX files
    // "reactNamespace": "React",
    // Modern browsers support all ES6 features, so ES6 is a good choice. You might choose to set a lower target if your code is deployed to older environments, or a higher target if your code is guaranteed to run in newer environments. The target setting changes which JS features are downleveled and which are left intact
    "target": "esnext",
    // This flag is used as part of migrating to the upcoming standard version of class fields. TypeScript introduced class fields many years before it was ratified in TC39. This flag switches to the upcoming ECMA runtime behavior
    // "useDefineForClassFields": false,
    /*
     * ------------------------------------------------------
     * CATEGORY: Compiler Diagnostics
     * ------------------------------------------------------
     */
    // Used to output diagnostic information for debugging. This command is a subset of extendedDiagnostics which are more user-facing results, and easier to interpret
    // "diagnostics": false,
    // Print names of files which TypeScript sees as a part of your project and the reason they are part of the compilation
    // "explainFiles": false,
    // You can use this flag to discover where TypeScript is spending its time when compiling. This is a tool used for understanding the performance characteristics of your codebase overall
    // "extendedDiagnostics": false,
    // This option gives you the chance to have TypeScript emit a v8 CPU profile during the compiler run. The CPU profile can provide insight into why your builds may be slow
    // "generateCpuProfile": "profile.cpuprofile",
    // Generates an event trace and a list of types
    // "generateTrace": "",
    // Print names of generated files part of the compilation to the terminal
    // "listEmittedFiles": false,
    // Print names of files part of the compilation. This is useful when you are not sure that TypeScript has included a file you expected
    // "listFiles": false,
    // Disable full type checking (only critical parse and emit errors will be reported)
    // "noCheck": false,
    // When you are trying to debug why a module isn't being included. You can set traceResolution to true to have TypeScript print information about its resolution process for each processed file
    // "traceResolution": false,
    /*
     * ------------------------------------------------------
     * CATEGORY: Projects
     * ------------------------------------------------------
     */
    // The composite option enforces certain constraints which make it possible for build tools (including TypeScript itself, under --build mode) to quickly determine if a project has been built yet
    // "composite": false,
    // In multi-project TypeScript programs, TypeScript will load all of the available projects into memory in order to provide accurate results for editor responses which require a full knowledge graph like 'Find All References'. If your project is large, you can use the flag disableReferencedProjectLoad to disable the automatic loading of all projects
    // "disableReferencedProjectLoad": false,
    // When working with composite TypeScript projects, this option provides a way to declare that you do not want a project to be included when using features like find all references or jump to definition in an editor
    // "disableSolutionSearching": false,
    // When working with composite TypeScript projects, this option provides a way to go back to the pre-3.7 behavior where d.ts files were used to as the boundaries between modules
    // "disableSourceOfProjectReferenceRedirect": false,
    // Tells TypeScript to save information about the project graph from the last compilation to files stored on disk. This creates a series of .tsbuildinfo files in the same folder as your compilation output
    // "incremental": false,
    // This setting lets you specify a file for storing incremental compilation information as a part of composite projects which enables faster building of larger TypeScript codebases
    // "tsBuildInfoFile": ".tsbuildinfo",
    /*
     * ------------------------------------------------------
     * CATEGORY: Output Formatting
     * ------------------------------------------------------
     */
    // Do not truncate error messages
    // "noErrorTruncation": false,
    // Whether to keep outdated console output in watch mode instead of clearing the screen every time a change happened
    // "preserveWatchOutput": false,
    // Stylize errors and messages using color and context, this is on by default - offers you a chance to have less terse, single colored messages from the compiler
    // "pretty": true,
    /*
     * ------------------------------------------------------
     * CATEGORY: Completeness
     * ------------------------------------------------------
     */
    // Use skipLibCheck instead. Skip type checking of default library declaration files
    // "skipDefaultLibCheck": false,
    // Skip type checking of declaration files. This can save time during compilation at the expense of type-system accuracy
    "skipLibCheck": true,
    /*
     * CATEGORY: Command Line */
    /*
     * ------------------------------------------------------
     * CATEGORY: Watch Options
     * ------------------------------------------------------
     */
    // When this option is enabled, TypeScript will avoid rechecking/rebuilding all truly possibly-affected files, and only recheck/rebuild files that have changed as well as files that directly import them
    // "assumeChangesOnlyAffectDirectDependencies": false
  },
  /* Watch Options */
  "watchOptions": {
    // The strategy for how individual files are watched
    // "watchFile": "useFsEvents",
    // The strategy for how entire directory trees are watched under systems that lack recursive file-watching functionality
    // "watchDirectory": "useFsEvents",
    // When using file system events, this option specifies the polling strategy that gets used when the system runs out of native file watchers and/or doesn't support native file watchers
    // "fallbackPolling": "dynamicPriority",
    // Synchronously call callbacks and update the state of directory watchers on platforms that don't support recursive watching natively
    // "synchronousWatchDirectory": false,
    // You can use excludeDirectories to drastically reduce the number of files which are watched during --watch
    // "excludeDirectories": [],
    // You can use excludeFiles to remove a set of specific files from the files which are watched
    // "excludeFiles": []
  },
  /* Type Acquisition */
  "typeAcquisition": {
    // Disables automatic type acquisition in JavaScript projects
    // "enable": false,
    // If you have a JavaScript project where TypeScript needs additional guidance to understand global dependencies, or have disabled the built-in inference via disableFilenameBasedTypeAcquisition. You can use include to specify which types should be used from DefinitelyTyped
    // "include": [],
    // Offers a config for disabling the type-acquisition for a certain module in JavaScript projects. This can be useful for projects which include other libraries in testing infrastructure which aren't needed in the main application
    // "exclude": [],
    // TypeScript's type acquisition can infer what types should be added based on filenames in a project. You can disable this via disableFilenameBasedTypeAcquisition
    // "disableFilenameBasedTypeAcquisition": false
  }
}