The --lib Flag: Including Type Definitions
What you'll learn: How to control which built-in JavaScript APIs TypeScript knows about based on your runtime environment.
What Is the --lib Flag?
When you write TypeScript, the compiler needs to know what features exist in your target environment. Does your code run in a modern browser with fetch() and Promise? Or in an older environment without those APIs? The --lib flag tells TypeScript which built-in type definitions to include so it can validate your code correctly.
Think of it like telling a librarian which reference books you need. If you're writing code for a browser, you need the "DOM" reference book. If you're writing Node.js code, you don't need DOM types at all.
How It Works
By default, TypeScript automatically chooses library definitions based on your --target setting. For example, "target": "ES2015" automatically includes ES2015 standard library types. But you can override this with --lib:
{
"compilerOptions": {
"target": "ES2015",
"lib": ["ES2015", "DOM"]
}
}
This tells TypeScript: "I'm targeting ES2015 JavaScript, and I need type definitions for both ES2015 features AND browser DOM APIs."
Common Library Options
ES5,ES2015,ES2020, etc. — JavaScript language featuresDOM— Browser APIs likedocumentandwindowDOM.Iterable— Iterable DOM collectionsWebWorker— Web Worker APIsScriptHost— Windows Script Host
Without the right lib entries, TypeScript will complain about APIs that don't exist in your declared environment.
Key Takeaway: The --lib flag explicitly declares which built-in JavaScript APIs and features TypeScript should recognize, giving you precise control over your environment's capabilities.