During a TypeScript migration, tsc reports errors that originate inside .d.ts files under node_modules. What does setting skipLibCheck to true in tsconfig.json actually skip, and what do you give up by leaving it on?

## What the flag does `skipLibCheck` tells the compiler not to type-check the *contents* of declaration files. "Declaration file" here means any `.d.ts`: the ones shipped inside packages, the `@types` packages you install, the built-in library files that describe the language and DOM, your own hand-written shims, and the declarations your own build emits. The crucial distinction is between *checking a declaration* and *using a declaration*. With the flag on, tsc still reads every declaration file and still uses the types in it to check your source. If a package declares `parse(input: string): number`, your call sites are checked against exactly that signature. What is skipped is the compiler verifying that the declaration file is internally coherent — that the types it references exist, that its own members are consistent, that it does not contradict itself. So this is not a blanket "ignore type errors" switch, and describing it that way in an interview is a red flag. ## Why the errors appear in the first place During a migration you inherit a dependency tree that was never checked, and several situations produce errors you cannot fix: - **Two versions of the same types.** Different packages depend on different versions of a `@types` package, so two declarations of the same global or interface end up in the program and conflict. - **A package written for a newer compiler.** Its declarations use syntax or built-in types your version does not know. - **A mismatch with `lib`.** A dependency's declarations reference DOM types while your `lib` setting includes only the Node-ish surface, or vice versa. - **A declaration file that is simply wrong.** Plenty of published types have never been checked against the code they describe. None of these are fixed by editing your own code, which is why blocking on them is pure friction. There is a secondary benefit too: skipping this work makes the type check meaningfully faster on a large dependency tree. ## What it costs you The cost lands on the declaration files you own. A migration typically produces shims for untyped dependencies, and with the flag on those shims are no longer validated. If a shim declares the wrong return type, tsc reports nothing — it trusts the declaration and checks your call sites against the lie: ```ts // legacy-lib.d.ts — a hand-written shim that is simply wrong declare module "legacy-lib" { export function version(): number; // it really returns a string } ``` Every call site now believes it holds a `number`. `version().toFixed(2)` compiles, and fails at runtime. The compiler never had a way to catch this — it cannot compare a declaration against a JavaScript implementation — but with `skipLibCheck` on you also lose the checks it *could* have done on the file's internal consistency. The same applies to declarations you publish. If your package emits `.d.ts` files and you never check them, you can ship types that do not compile for your consumers even though your own build is green. ## How to use it well Turn it on. In practice almost every real project runs with `skipLibCheck: true`, and it is on by default in many project templates — the friction of policing other people's declaration files is not worth the value. Treat the migration framing honestly: it is a stopgap in the sense that it unblocks you immediately, but for most applications it is a permanent, reasonable setting. What should not become permanent is the loss of coverage over declarations you own: - If you **publish** a package, run one extra check without the flag, or check the emitted `.d.ts` files separately, so you do not ship broken types. - Keep hand-written shims minimal and prefer replacing them with real `@types` packages or upstream types as they become available; a shim is an assertion nobody verifies. - Revisit occasionally. If it was turned on to work around one bad dependency, that dependency may have been fixed, and a clean run without the flag is a cheap thing to try. ## What it will not do for you It will not silence errors in your `.ts` files, it will not make an untyped package typed, and it will not resolve a genuine version conflict — it only stops that conflict being reported from inside the declarations. If your code breaks because two libraries disagree about a shared type, you will still see it at the point where your own code sits between them.