TypeScript Compiler Configuration

Parent: TypeScript Expert · Published reference · snapshot 2026-09-08 · skill lang-js-ts/references/typescript-compiler-config.md

↓ Facts as markdown all context files

A lang-js-ts reference for the tsconfig.json file and the full compilerOptions surface. The

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

TypeScript Compiler Configuration — `tsconfig.json` & `compilerOptions`

A lang-js-ts reference for the tsconfig.json file and the full compilerOptions surface. The goal: pick a correct, version-appropriate config the first time, know what each strictness flag costs, and copy a sane baseline for a Node app, a bundler/web app, or a published library. Defer module resolution algorithm internals, project references / tsc -b, and external bundler config to the siblings listed in the provenance block. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#typescript-compiler-configuration-tsconfigjson-compileroptions]

Overview

tsconfig.json marks a directory as the root of a TypeScript project and tells tsc (and every editor, bundler plugin, and ts-node/tsx) what files to compile and under what rules. Running tsc with no input files makes it search up from the CWD for the nearest tsconfig.json; tsc -p ./path points at a specific one. The shape is two halves: a small set of top-level fields (which files, what to extend) and the large compilerOptions object (how to type-check, resolve, and emit). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#overview]
Version anchor (memorize - these drive "is this flag available / on" questions): [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#overview]
> Defaults vs tsc --init. Through TS 5.x the compiler defaults are permissive (strict: false, > target: ES5, module keyed off target), even though tsc --init scaffolds a strict-on file - > "default" in this doc means the compiler default for the stated version line, not what a generated > file shows. TS 6.0 changes the compiler defaults themselves (see the TS 6.0 delta). The robust > habit either way: set strict, target, module, and lib explicitly so behavior doesn't shift > under you across versions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#overview]

Top-level fields (brief — deep dives are deferred)

extends - inherit another config: a relative path or a package, e.g. "@tsconfig/node20/tsconfig.json". Accepts an array (TS 5.0+) merged left→right. The child wins on conflicts; files/include/exclude from the parent are overwritten (not merged) if redefined. Relative paths/outDir in the parent resolve against the parent's location. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#top-level-fields-brief-deep-dives-are-deferred]
files - an explicit allowlist of files. No globs. Best for tiny projects; otherwise use include. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#top-level-fields-brief-deep-dives-are-deferred]
include - glob patterns ("src/**/"). If omitted, defaults to everything under the config dir (minus exclude). `/?/** supported; patterns without an extension match .ts/.tsx/.d.ts (and .js/.jsx when allowJs`). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#top-level-fields-brief-deep-dives-are-deferred]
exclude - globs removed from include (defaults to node_modules, bower_components, jspm_packages, and outDir). exclude only filters include; it does not stop a file pulled in by an import or a /// <reference>. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#top-level-fields-brief-deep-dives-are-deferred]
references - array of { "path": "../pkg" } for project references (composite builds). Deep coverage → typescript-project-references-monorepo. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#top-level-fields-brief-deep-dives-are-deferred]

Type-checking / strictness

strict is a bundle switch. Setting "strict": true turns on all eight family members at once; you can then re-disable any single one ("strict": true, "strictNullChecks": false) - the explicit flag overrides the bundle. The eight strict-family flags: [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#type-checking-strictness]
> The exact membership of the strict family is these eight per the TSConfig reference. Newer TS > lines have floated additional strict-gated checks; verify against the reference for your version > before relying on one beyond these eight. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#type-checking-strictness]
Standalone checks (NOT enabled by strict - opt in individually): [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#type-checking-strictness]
The @tsconfig/strictest preset enables the full set above (plus noUnusedLocals, noUnusedParameters, noImplicitReturns, etc.) for green-field projects that can afford it. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#type-checking-strictness]

Modules

These four options are interdependent - set them as a group, not piecemeal. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
module - the module format tsc emits and the import syntax it understands: [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "commonjs" - require/module.exports output. Legacy Node / CJS packages. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "node16" / "nodenext" - emit format is chosen per file from the nearest package.json "type" (and .mts/.cts extension). The correct choice for code that runs in modern Node. nodenext tracks the latest Node behavior; node16 pins to the Node 16 semantics. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "esnext" / "es2015"/"es2020"/"es2022" - pure ESM output at the stated level. Use for code a bundler will consume, or pure-ESM libraries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "preserve" (TS 5.4) - leave imports/import() exactly as written, no rewriting. Implies moduleResolution: bundler. The modern "I'm handing this to a bundler" choice. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- (Deprecated/legacy: amd, umd, system, none.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
moduleResolution - how a specifier maps to a file: [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "node10" (the option formerly named "node") - classic Node CJS resolution. No exports/imports field support. Legacy only. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "node16" / "nodenext" - modern Node resolution honoring package.json "exports"/"imports", conditional exports, and .mts/.cts. Pair with module: node16/nodenext. Required for correctly typing dual-format packages. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "bundler" (TS 5.0) - models esbuild/Vite/webpack/Parcel: extensionless imports allowed (like CJS) but prefers import conditions in exports (like ESM). For app code consumed by a bundler. Not for published libraries - it hides resolution problems your consumers (who may not bundle) would hit; ship with node16/nodenext instead. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- "classic" - pre-Node TS resolution. Effectively never use it. (Resolution algorithm internals + exports/imports mechanics → nodejs-module-resolution.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
target - the ECMAScript version tsc downlevels syntax to (e.g. es2015…es2023, esnext). Drives the default lib and the default module. Through 5.x the default is ES5; pick at least es2022 for modern runtimes (top-level await, class fields, Error.cause). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
lib - which built-in type declarations to include (e.g. ["es2022", "dom", "dom.iterable"]). Omitting it derives a set from target. Set it explicitly to control DOM availability: include dom for browser code, omit it for pure Node/server code so document/window don't type-check. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
Path mapping & related: [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- baseUrl - base directory for resolving bare specifiers. (Deprecated in TS 6.0; prefer paths without it, or package imports.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- paths - remap import specifiers to locations, e.g. { "@app/": ["./src/"] }. tsc and editors honor these for type-checking only - they do not rewrite emitted paths. A bundler, tsc-alias, or package.json "imports" must make them work at runtime. Node's native runner ignores paths. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- rootDir - the input root that mirrors into outDir (controls output folder structure). rootDirs merges multiple virtual roots into one. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- outDir - where emitted .js/.d.ts go. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- resolveJsonModule - allow import data from "./x.json" with an inferred type. Requires a module that supports it (most do except some legacy modes). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- allowImportingTsExtensions (5.0) - permit import "./x.ts" (explicit TS extension). Only allowed with noEmit or emitDeclarationOnly (since tsc can't emit a .ts import). Needed for Node's native type-stripping workflow. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- moduleDetection - "auto" (default; a file with any import/export, or under module: node16/nodenext with "type":"module", is a module), "force" (treat every file as a module - recommended to avoid global-scope surprises), "legacy". [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]
- resolvePackageJsonExports / resolvePackageJsonImports - consult the package.json "exports"/"imports" fields. Default true under node16/nodenext/bundler. (Field mechanics → nodejs-module-resolution.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#modules]

Emit & interop

declaration - emit .d.ts files. Mandatory for a published library. Defaults true when composite is on, else false. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
declarationMap - emit .d.ts.map so consumers' "go to definition" jumps to your .ts source, not the .d.ts. Ship for libraries with source. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
sourceMap - emit .js.map for runtime debugging. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
noEmit - type-check only, produce no files. The standard setting when a bundler (or Node's strip-types) does the actual transpile and tsc is the type gate. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
isolatedModules - guarantee every file can be transpiled alone, without cross-file type info (which is exactly how esbuild/swc/Babel/Node-strip operate). It bans constructs needing whole-program knowledge - re-exporting a type without export type, const enum, certain namespace patterns. Turn it on whenever a single-file transpiler is in the pipeline. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
verbatimModuleSyntax (5.0) - leave any import/export without a type modifier exactly as written, and drop anything with type. Replaces the deprecated importsNotUsedAsValues + preserveValueImports. Makes value-vs-type imports explicit and prevents accidental elision - pair it with isolatedModules/erasableSyntaxOnly. Caveat: it won't rewrite ESM syntax to require, so don't combine it with module: commonjs if you write import/export. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
esModuleInterop - generate interop helpers so import express from "express" works against a CJS module without a real default export. Implies allowSyntheticDefaultImports. Effectively always-on in modern configs (and undisablable in TS 6.0). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
allowSyntheticDefaultImports - allow default-style imports from modules lacking a default export, for type-checking only (no emit change). Implied by esModuleInterop. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]
erasableSyntaxOnly (5.8) - error on TS constructs that emit runtime code: enum, namespace with runtime members, parameter properties (constructor(private x)), import =. Mirrors exactly what Node's native type-stripping refuses, so the editor catches the mismatch instead of a runtime crash. Pair with verbatimModuleSyntax. (Node runtime side → nodejs-typescript-and-runtime-features.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#emit-interop]

JS interop & JSX

allowJs - let .js/.jsx files into the program (imported by, or alongside, .ts). Needed for incremental migration and for emitting from a JS codebase. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#js-interop-jsx]
checkJs - type-check those .js files (using JSDoc annotations). Per-file opt-in/out via // @ts-check / // @ts-nocheck. Requires allowJs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#js-interop-jsx]
jsx - JSX transform: "preserve" (emit .jsx, leave JSX for a bundler), "react" (classic React.createElement), "react-jsx" (the automatic runtime - no import React needed; the modern default for React 17+), "react-jsxdev", "react-native". [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#js-interop-jsx]
jsxImportSource (4.1) - the module the automatic runtime imports jsx/jsxs from (default "react"); set to "preact", "@emotion/react", etc. Only meaningful with jsx: react-jsx/react-jsxdev. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#js-interop-jsx]

The TS 6.0 delta (current as of June 2026)

TypeScript 6.0 (released March 2026) is the last JavaScript-based release before the Go-based TS 7.0 ("native"). Per the official handbook release notes it changes compiler defaults - relevant to this skill: [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
- strict now defaults true (was false). The notes are explicit: "If you were relying on the previous default of false, you'll need to explicitly set "strict": false in your tsconfig.json." [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
- module defaults esnext (ESM is now the dominant format). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
- target defaults to the most recent supported ECMAScript spec - a floating target, currently es2025. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
- types defaults [] (no longer auto-pulls every installed @types package - declare what you need). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
- rootDir defaults to the directory containing tsconfig.json. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
- noUncheckedSideEffectImports defaults true (already true on the 5.6+ reference); libReplacement now defaults false for performance. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]
It also adds --stableTypeOrdering (to diff 6.0 vs 7.0 output) and deprecates/removes legacy surface (target: es5 + --downlevelIteration, moduleResolution: node10/classic, module: amd/umd/system/none, --outFile, baseUrl). Practical takeaway: explicitly set strict, target, module, and lib in your config so behavior is identical across 5.x and 6.0 instead of relying on defaults that shifted. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#the-ts-60-delta-current-as-of-june-2026]

Tools / Frameworks

tsc --init - scaffold a commented tsconfig.json. The generated defaults have grown stricter over versions; treat the output as a starting point, not gospel - prune comments and pin the four module/target options. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#tools-frameworks]
@tsconfig/bases - official community base configs you extends: @tsconfig/node20, @tsconfig/node22, @tsconfig/strictest, @tsconfig/recommended, framework bases (@tsconfig/vite-react, etc.). Inherit one and override the few project-specific keys. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#tools-frameworks]
tsc --showConfig - print the fully-resolved config (after extends merging and defaults). The fastest way to answer "what is actually in effect here?" [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#tools-frameworks]
tsc --explainFiles / --listFilesOnly - show why each file is in the program (which include/import/reference pulled it in). Use when include/exclude isn't behaving. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#tools-frameworks]
tsc --noEmit - the type-check gate to run in CI when a bundler or Node strip-types does the real build. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#tools-frameworks]
tsc-alias / bundler resolve.alias - make paths work at runtime (since tsc doesn't rewrite them). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#tools-frameworks]

Methodology

Inherit, don't hand-roll. Start from @tsconfig/node22 (or a framework base) via extends, then override only what's project-specific. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#methodology]
Set the module quartet together by runtime target: Node → module: nodenext + moduleResolution: nodenext; bundler/web → module: preserve (implies bundler) + noEmit; library → module: nodenext (or esnext) + declaration: true. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#methodology]
Turn on strict (default in 6.0) and, for new code, the high-value standalone checks noUncheckedIndexedAccess + noImplicitOverride. Add exactOptionalPropertyTypes/@tsconfig/strictest only if the team will pay the friction. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#methodology]
Pin target and lib explicitly (e.g. es2022; ["es2022"] server vs ["es2022","dom","dom.iterable"] web) so the 6.0 default flips don't silently change behavior. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#methodology]
If a single-file transpiler is in the pipeline (esbuild/swc/Vite/Node strip-types), set isolatedModules: true + verbatimModuleSyntax: true (+ erasableSyntaxOnly for the native-Node path). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#methodology]
Verify with tsc --showConfig and a tsc --noEmit run before trusting the file. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#methodology]

Practical Patterns

Node app (TS 5.x/6.0, transpiled by tsc): [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#practical-patterns]
Bundler / web app (Vite/esbuild/webpack do the transpile; tsc is the type gate): [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#practical-patterns]
Published library (dual-friendly types, source-mapped declarations): [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#practical-patterns]
Node native type-stripping (zero build; tsc --noEmit only validates): [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#practical-patterns]
(Native-runtime behavior itself → nodejs-typescript-and-runtime-features.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#practical-patterns]

Anti-Patterns

Mixing module modes. module: esnext with moduleResolution: node10 (or bundler with module: commonjs) gives wrong resolution/emit. Keep module/moduleResolution consistent with the runtime. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
moduleResolution: bundler in a published package. It validates only the bundler case and hides breakage for consumers using plain Node resolution. Libraries → node16/nodenext. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
Expecting paths to work at runtime. tsc never rewrites them; without a bundler/tsc-alias/package imports, the emitted JS has unresolved bare specifiers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
Leaving target: ES5 (5.x default) unset on a modern runtime - bloated downlevel output and missing lib types. Always pin target. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
enum/namespace/parameter-properties under isolatedModules or a strip-types runtime - they need whole-program emit; use erasableSyntaxOnly to catch them at author time. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
skipLibCheck everywhere as a crutch - it's a performance win, but it can mask genuine conflicts between @types packages; don't reach for it to silence a real type error. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
Re-exporting a type without export type when isolatedModules/verbatimModuleSyntax is on - a single-file transpiler can't tell it's type-only and may emit a broken value import. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]
Relying on TS 6.0's default flips. Be explicit about strict/target/module/lib so a 5.x and a 6.0 toolchain produce identical results. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#anti-patterns]

Troubleshooting

"Cannot use import statement outside a module" / wrong require-vs-import emit → module/moduleResolution don't match the runtime; switch to nodenext and check the package's "type". [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
paths import fails at runtime (works in editor) → expected; wire tsc-alias, a bundler alias, or package.json "imports". [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
"This import path can only be used with allowImportingTsExtensions" → you imported ./x.ts; set allowImportingTsExtensions: true (and noEmit/emitDeclarationOnly). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
"X is declared but never used" / unexpected unused errors → a @tsconfig/strictest base enabled noUnusedLocals/noUnusedParameters; relax or prefix with _. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
enum/parameter-property errors under a no-emit setup → erasableSyntaxOnly is on (or the runtime strips types); rewrite to erasable constructs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
Config changes seem ignored → run tsc --showConfig; an extends parent or an editor pinning a different tsconfig is overriding you. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
A file you expected isn't compiled → it's outside files/include or hit exclude; exclude can't remove a file reached via import. Use tsc --explainFiles. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
New type errors after a TS upgrade → strict may gate additional checks in the new line (and 6.0 flips defaults); pin versions and read that release's notes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]
DOM globals (document, window) missing or unexpectedly present → set lib explicitly (include/exclude dom). [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#troubleshooting]

References

TypeScript - TSConfig Reference (every option, defaults): https://www.typescriptlang.org/tsconfig/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript Handbook - What is a tsconfig.json: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript Handbook - Modules: Choosing Compiler Options: https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript 5.0 release notes (verbatimModuleSyntax, bundler, allowImportingTsExtensions): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript 5.4 release notes (module: preserve): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-4.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript 5.6 release notes (noUncheckedSideEffectImports): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-6.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript 5.8 release notes (erasableSyntaxOnly, rewriteRelativeImportExtensions): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-8.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
TypeScript 6.0 release notes (default flips, deprecations, last JS-based release): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
@tsconfig/bases (community base configs): https://github.com/tsconfig/bases [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]
Total TypeScript - The TSConfig Cheat Sheet (Matt Pocock baselines): https://www.totaltypescript.com/tsconfig-cheat-sheet [archived source: https://llms-explorer.com/sources/mdb-context-hub/typescript-compiler-config/#references]

Where this helps

Setting up a new TypeScript project and needing to choose the interdependent module/moduleResolution/target/lib quartet correctly for the actual runtime (Node, bundler, or published library). [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Debugging "Cannot use import statement outside a module" or unexpected require-vs-import emit, caused by a module/moduleResolution mismatch. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Deciding how much of the strict family to turn on for an existing codebase without breaking the whole build at once. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Migrating a config forward to TypeScript 6.0, where several long-standing defaults (strict, module, target, types) flip. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Project ideas

Build a project's tsconfig.json by extending a community base (@tsconfig/node22, @tsconfig/strictest) and overriding only the project-specific fields, instead of hand-rolling every option. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Set up a "bundler + type-gate" split config where esbuild or Vite does the actual transpile and a separate tsc --noEmit run is the CI type-check gate. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Build a dual-package library config (ESM + CJS) with the module/moduleResolution quartet set correctly and a types condition placed first in the exports map. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Write a small script that runs tsc --showConfig to print the fully-resolved config after extends merging, useful for debugging "what's actually in effect" in a nested-config repo. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Common mistakes

Setting module: esnext with moduleResolution: node10 (or bundler with module: commonjs) - the module and moduleResolution options are interdependent and must match the actual runtime. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Shipping moduleResolution: bundler in a published npm package - it only validates the bundler-consumption case and hides breakage for consumers using plain Node resolution. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Assuming tsconfig paths get rewritten at runtime - tsc never rewrites them; without a bundler, tsc-alias, or package.json imports, the emitted JS has unresolved bare specifiers. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Relying on TypeScript 6.0's flipped defaults (strict now true, module now esnext) without pinning them explicitly, so a 5.x and 6.0 toolchain silently produce different behavior on the same source. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

Through TS 5.x the compiler's actual defaults are permissive (strict: false, target: ES5) even though tsc --init scaffolds a strict-looking file - the "default" and the "scaffolded starting point" are two different things. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
baseUrl is deprecated in TS 6.0, but many existing configs and guides still rely on it for path resolution, creating a forward-compatibility gap that needs planning around. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
skipLibCheck is a real performance win but can mask genuine conflicts between two @types packages - using it as a blanket crutch risks silencing a legitimate type error, not just a slow one. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
The TS 6.0 default flips (strict true, module esnext, target floating to the latest spec, types defaulting to []) mean a config that worked identically on 5.x and 6.0 can no longer be assumed - every default needs re-pinning. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Children

No children recorded.

← the whole tree · 3D view· how to read this page