TypeScript Documentation
Knowledge base from the official TypeScript documentation (TypeScript Handbook v2, Reference, and Modules Reference) — the TypeScript 5.x language, type system, and module system. Use when writing or debugging TypeScript types, choosing between interface/type/generics/conditional-types/mapped-types, looking up a utility type (Partial/Pick/Omit/ReturnType/etc.), understanding class visibility/decorators/mixins, or configuring module/moduleResolution compiler options for Node.js/bundlers/libraries.
TypeScript Documentation
Source: TypeScript-Website (microsoft/TypeScript-Website), Handbook v2 + Reference + Modules Reference | Chapters: 36 | Generated: 2026-08-25
How to Use This Skill
- Without arguments — load Core Patterns & Conventions below for the language's high-signal defaults (strictness, narrowing, generics discipline, module settings).
- With a topic — ask about
generics,mapped types,decorators,module resolution, or another indexed topic; I find and read the matching chapter. - With a chapter — ask for
ch030(Utility Types); I load that specific chapter. - Browse — ask "what chapters do you have?" to see the full index below.
When you ask about a topic not covered in Core Patterns below, I will read the relevant chapter file before answering.
Core Patterns & Conventions
Structural typing, always. Two types are compatible purely by shape — never by declared name or implements/extends. Don't reach for implements expecting it to change a class's inferred types; it's a compatibility check only.
Turn on strict from day one. New codebases should never start unstrict — the two flags that matter most are noImplicitAny (no silent any fallback) and strictNullChecks (null/undefined stop being universally assignable).
Default to const, then interface. Use let only for genuinely reassigned bindings, never var. Default to interface for object shapes; reach for type only for unions, tuples, primitive aliases, or intersection composition.
Model closed variant sets as discriminated unions, not optional-field soup. A shared literal kind/type field with required (not optional) per-variant properties beats one interface full of optional fields — and unlocks exhaustiveness checking via never in a switch default.
Reach for a built-in utility type before hand-writing a mapped/conditional type. Partial/Required/Readonly/Pick/Omit/Record/Exclude/Extract/NonNullable/ReturnType/Parameters/InstanceType/Awaited cover the overwhelming majority of shape-transform needs (Ch30).
Generics should relate at least two things. If a type parameter appears only once across a signature, drop it — it isn't relating anything, a concrete type is simpler and equally correct (Ch04, Ch07).
readonly/Readonly<T>/as const are compile-time-only. None of them are runtime immutability guarantees — mutation through an aliased mutable reference, or through private's "soft" bracket-notation escape hatch, still works. Use JS #privateField/Object.freeze for real enforcement (Ch05, Ch12).
Pick module compiler options by consumer, not by habit. module: nodenext for real Node.js execution, esnext + moduleResolution: bundler for bundler/Bun/tsx pipelines, node18 (implying node16 resolution) for a published library compiled with tsc — mismatching these produces code that type-checks but crashes at the actual runtime (Ch32, Ch34, Ch36).
Chapter Index
Handbook — Basics
| # | Title | Key Concepts |
|---|---|---|
| ch001 | The Basics | static vs dynamic typing, tsc, strictness flags |
| ch002 | Everyday Types | primitives, unions, literal types, interface vs type, as const |
| ch003 | Narrowing | type guards, discriminated unions, exhaustiveness via never |
| ch004 | More on Functions | overloads, this params, void/unknown/never, rest params |
| ch005 | Object Types | readonly, index signatures, excess property checks, tuples |
Handbook — Type Manipulation
| # | Title | Key Concepts |
|---|---|---|
| ch006 | Type Manipulation Overview, keyof & typeof | key unions, value-to-type bridging |
| ch007 | Generics | type parameters, constraints, defaults, variance |
| ch008 | Indexed Access Types | Type["prop"], element type extraction |
| ch009 | Conditional Types | T extends U ? X : Y, infer, distribution |
| ch010 | Mapped Types | { [P in keyof T]: ... }, modifiers, key remapping |
| ch011 | Template Literal Types | string literal composition, Uppercase/Capitalize |
Handbook — Classes & Modules
| # | Title | Key Concepts |
|---|---|---|
| ch012 | Classes — Members, Heritage & Visibility | fields, getters/setters, implements, public/protected/private |
| ch013 | Classes — Static, Generics, this, Abstract | static blocks, this types, abstract classes, parameter properties |
| ch014 | Modules | ES Module syntax, type-only imports, CommonJS, module/target |
| ch015 | Type Declarations | .d.ts files, lib, DefinitelyTyped/@types |
| ch016 | Understanding Errors | reading assignability error chains |
Reference
| # | Title | Key Concepts |
|---|---|---|
| ch017 | Advanced Types (Legacy) | cross-reference page, homomorphic mapped types, infer variance |
| ch018 | Declaration Merging | interface/namespace merging, module augmentation |
| ch019 | Decorators (Stage 2) | class/method/property/parameter decorators |
| ch020 | Enums | numeric/string enums, const enum, keyof typeof |
| ch021 | Iterators and Generators | Iterable<T>, for..of vs for..in |
| ch022 | JSX | jsx modes, intrinsic vs value-based elements |
| ch023 | Mixins | class-expression composition, constrained constructors |
| ch024 | Namespaces and Modules | choosing modules over namespaces, pitfalls |
| ch025 | Namespaces | namespace, multi-file namespaces, ambient namespaces |
| ch026 | Symbols | symbol, unique symbol, well-known symbols |
| ch027 | Triple-Slash Directives | /// <reference ... /> forms |
| ch028 | Type Compatibility | structural subtyping, function bivariance, any/unknown/never table |
| ch029 | Type Inference | best common type, contextual typing |
| ch030 | Utility Types | Partial/Pick/Omit/ReturnType/etc. reference |
| ch031 | Variable Declarations | var/let/const, TDZ, destructuring |
Modules Reference
| # | Title | Key Concepts |
|---|---|---|
| ch032 | Module Syntax Extras & module Option | type-only imports, export =, ambient modules, module values |
| ch033 | Module Resolution Reference | extension substitution, paths, node_modules, package.json exports |
| ch034 | Module Theory | host modeling, output-file mental model, declaration file pairing |
| ch035 | ESM/CJS Interop | __esModule, esModuleInterop history, Node.js interop quirks |
| ch036 | Choosing Compiler Options | practical settings by consumer (bundler/Node/library) |
Topic Index
- Abstract classes → ch013
any/unknown/never→ ch004, ch028- Classes (visibility, heritage) → ch012
- Classes (static, generics,
this, abstract) → ch013 - Compiler options (module setup) → ch032, ch033, ch036
- Conditional types → ch009, ch017
- Decorators → ch019
- Discriminated unions → ch003
- Enums → ch020
- ESM/CJS interop → ch035
- Exhaustiveness checking → ch003, ch020
- Generics → ch007
infer→ ch009, ch017, ch030- Interfaces vs. type aliases → ch002, ch005
- JSX → ch022
keyof/typeof→ ch006- Mapped types → ch010, ch017
- Mixins → ch023
- Module resolution → ch033, ch034
- Module syntax (import/export) → ch014, ch032
- Namespaces → ch024, ch025
- Narrowing → ch003, ch017
- Node.js module setup → ch032, ch036
- Overloads → ch004, ch012
- Structural typing / compatibility → ch028
- Symbols → ch026
- Template literal types → ch011
- Tuples → ch005
- Type declarations (.d.ts) → ch015
- Type inference → ch029
- Utility types (Partial, Pick, Omit, ReturnType, ...) → ch030
- Variable declarations (var/let/const) → ch031
Supporting Files
- glossary.md — key terms with definitions
- patterns.md — recurring idioms and when to reach for them
- cheatsheet.md — decision tables (interface vs type, which utility type, module settings by consumer, etc.)
Scope & Limits
This skill covers the official TypeScript documentation as aggregated from the TypeScript-Website repository (Handbook v2, Reference, Modules Reference), fetched 2026-08-23. It documents the TypeScript language and compiler itself — type syntax, the module system, and compiler configuration — not any specific framework's usage patterns built on top of it.
Related skills in this library: zod-docs (runtime validation deriving TypeScript types from schemas — complements this skill's static-only type system), react-docs (React itself is written and typed in TypeScript; JSX chapter here (ch022) covers the language-level mechanics React's own typings build on), tanstack-query-docs and tanstack-table-docs (both heavily generic, TypeScript-first libraries — Ch07 Generics and Ch30 Utility Types are directly relevant background for their advanced typing patterns), base-ui-docs and radix-primitives-docs (React component libraries using generics/this types/discriminated unions extensively in their own type definitions).
Decorators (ch019) cover the experimental stage-2 implementation (experimentalDecorators), not the native stage-3 decorators shipped since TypeScript 5.0 — check which model a given project actually targets before applying that chapter's patterns.
Advanced Types (ch017) is explicitly a legacy/superseded reference page in the source documentation itself — prefer the newer Narrowing/Mapped Types/Conditional Types/Classes chapters for the same mechanics; ch017 exists mainly to cover the handful of details (homomorphic mapped types, infer variance) not spelled out elsewhere.