Course contentsShow
← TypeScript
Lesson 80 of 1,7962. Setup and ToolingFree lesson

The --lib Flag: Including Type Definitions

Control which built-in type definitions are included based on your target environment and APIs.

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 features
  • DOM — Browser APIs like document and window
  • DOM.Iterable — Iterable DOM collections
  • WebWorker — Web Worker APIs
  • ScriptHost — 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.