tsconfig explained
What the core tsconfig.json options control — target, lib, module, include, outDir, noEmit — and how to pick values for a real project.
tsconfig explained
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- A `tsconfig.json` answers four questions for the compiler: which files belong to the project, which runtime the code will run in, how strict to be, and what (if anything) to output.
- `include`, `exclude`, and `files` pick the source files. `exclude` only filters what `include` matched, so a file that another included file imports is still checked.
- `target` decides which JavaScript syntax the output may use, while `lib` decides which built-in APIs the checker believes exist. They are related but separate, and `lib` defaults from `target`.
- `module` decides what module format the output uses and, through the related resolution rules, how imports are looked up. Modern projects mostly choose `nodenext` for code Node runs directly, or `preserve` with `moduleResolution: bundler` for code a bundler processes.
- `outDir` and `rootDir` control where emitted files land, and `noEmit` turns emission off entirely when another tool produces the JavaScript.
Four questions the compiler needs answered
The compiler can’t guess how your project works. Before it checks a single line it needs to know four things:
- Which files are part of this project?
- Where will the code run — which JavaScript version, which built-in APIs?
- How strict should the checks be?
- What to output, and where — or nothing at all?
tsconfig.json is where you write the answers down once, instead of passing flags on every run. Here is a realistic config for a small Node project that tsc builds:
{
"compilerOptions": {
"target": "es2022",
"module": "nodenext",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"skipLibCheck": true
},
"include": ["src"]
}
Which files: include, exclude, files
include takes glob patterns, and "src" means everything under that folder. exclude removes matches from that set and defaults to node_modules plus your outDir. files lists individual files exactly, which is rarely needed.
The subtle part: these only choose the entry points. If src/app.ts imports scripts/helper.ts, the compiler follows the import and checks helper.ts too, even if it sits in exclude. exclude stops a file being picked up by the glob. It does not hide it from the import graph.
Where it runs: target and lib
These two are easy to confuse because they sound alike.
target controls the output syntax. With target: "es2015", tsc rewrites newer syntax such as optional chaining (a?.b) into longer equivalents that older engines understand. With es2022 or later, most modern syntax passes through untouched. Pick the newest version your oldest supported runtime understands. Current Node versions handle recent targets fine.
lib controls the checker’s knowledge of built-in APIs: which methods exist on Array, whether Promise and Map exist, and whether browser globals like document exist. It doesn’t add any code. It defaults to the APIs that match target, plus the DOM.
{
"compilerOptions": {
"target": "es2022",
"lib": ["es2023", "dom"]
}
}
Think of target as the dialect you write the output letter in, and lib as the list of facilities you assume the recipient’s building has. Claiming a facility in lib doesn’t build it. If you list es2023 and your runtime lacks Array.prototype.findLast, the checker is happy and the program still crashes. For a Node-only project, leaving out dom is a good habit, so the checker rejects accidental uses of window. Types for Node’s own APIs come from the @types/node package, a topic for the declaration-files lessons.
Output format: module and friends
module decides which module system the emitted JavaScript uses, and it also shapes how the compiler finds the file behind each import. Older guides show commonjs or esnext. The values you’ll mostly see in current projects:
nodenext— for code Node runs directly. The compiler follows Node’s own rules, including the"type"field inpackage.jsonand the requirement for file extensions in relative ESM imports.preserve, usually withmoduleResolution: "bundler"— for code a bundler will process. Imports are left as written and resolved the loose way bundlers do it, with no extensions required.
A related option, verbatimModuleSyntax, makes the compiler leave each import and export exactly as written apart from removing ones marked import type. It forces you to be explicit about type-only imports, which matters to tools that strip types file by file. The full rules of resolution belong to module resolution. For now, the first choice is simply “does Node run this, or does a bundler?”
What comes out: outDir, rootDir, noEmit
outDir puts emitted .js files in a separate folder instead of next to the sources. rootDir sets which source folder maps onto outDir, so src/server/index.ts becomes dist/server/index.js. Set it explicitly. Otherwise the compiler infers it from your file layout, and adding one file outside src can quietly shift your whole output tree.
If tsc is not the tool producing your JavaScript, say Vite or a framework build is, turn emission off:
{
"compilerOptions": {
"noEmit": true,
"module": "preserve",
"moduleResolution": "bundler"
}
}
strict and the other check flags deserve their own lesson, and they get one next. skipLibCheck skips type-checking declaration (.d.ts) files, most of which come from dependencies. That speeds up builds and avoids errors in code you don’t own. Most projects turn it on.
What the video covers
Simon’s walkthrough goes through tsconfig in roughly the order used here: build output, strictness, target, lib and environment, and the module system, with a live project so you can watch each option change the result. It was recorded in the TypeScript 5.0 era, so it gives little weight to module: "preserve", verbatimModuleSyntax, or newer nodenext behavior, and the tsc --init output it shows is longer than what current versions generate. The sections above fill those gaps. Matt Pocock’s cheat sheet in the links is a good compact reference to keep open while editing a real config.
Check yourself
You set `target` to `es2017` and call `array.at(-1)`, and the checker says `at` does not exist. What is going on?
`lib` defaults to match `target`, so the checker only knows the built-in APIs from ES2017, and `Array.prototype.at` arrived later. Raising `target`, or setting `lib` to include a newer ES version, tells the checker the method exists. It is your job to make sure the runtime really has it.
Why might a file in your `exclude` list still show up in the type check?
`exclude` only removes files from the set `include` matched as entry points. If an included file imports the excluded one, the compiler follows the import and checks it anyway.
What is the difference between `target` and `lib`?
`target` controls the output, meaning which syntax `tsc` downlevels when it emits JavaScript. `lib` controls the checker's knowledge of built-in globals such as `Promise`, `Map`, or the DOM. One changes the emitted code, the other changes which APIs type-check.
When does `noEmit: true` make sense in a tsconfig?
When a different tool produces the runnable JavaScript, for example a bundler like Vite, a framework build, or a runtime that strips types. `tsc` then only checks types, and having it emit files as well would create duplicate, unused output.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.