TypeScript Overview
TypeScript is a statically typed superset of JavaScript that compiles to plain JavaScript. Every valid JavaScript file is a valid TypeScript file. TypeScript adds a type system that is erased at compile time — it produces no runtime overhead. The compiler strips all type annotations and produces idiomatic JavaScript that runs in any environment where JavaScript runs: browsers, Node.js, Deno, edge runtimes.
The fundamental value TypeScript delivers is moving a class of errors from runtime to compile time. A mistyped property name, a function called with the wrong argument type, a null dereference — these are errors that JavaScript discovers only when the code runs, often in production, often for a specific user in a specific code path that was not exercised during testing. TypeScript discovers them when the code is written, in the editor, before a single test runs.
The tradeoff is real. TypeScript requires a compilation step and a tsconfig, adds syntax to read and write, and creates a maintenance obligation for type declarations when third-party libraries ship without them. The question is not whether TypeScript is good but whether the project's context — team size, codebase lifetime, complexity — justifies the overhead. For most teams building anything that will be maintained beyond a few months, it does. The cost of miscommunication between modules, of runtime errors that type checking would have caught, accumulates faster than the cost of maintaining types.
This overview maps the TypeScript category: each article covers one facet of the type system or one application concern. The order — fundamentals, generics, utility types, narrowing, declarations, configuration, React integration, runtime validation — mirrors the order a developer would encounter these topics when adding TypeScript to a real project.
Design Thinking
TypeScript's type system is structural, not nominal
TypeScript uses structural typing: two types are compatible if they have the same shape, regardless of their names. A function expecting { name: string } accepts any object that has a name string property — it does not require that the object was declared as a specific named type. This is different from nominal typing in languages like Java or C#, where type compatibility is determined by explicit inheritance or interface implementation, not by shape.
The practical consequence is that TypeScript interfaces and type aliases describe the shape of data, and any value that satisfies the shape satisfies the type. This makes TypeScript naturally compatible with the duck-typed style of JavaScript: code that was written without types can often be described by a type that fits its shape, without changing the code. It also means that two separately defined interfaces with the same shape are interchangeable — there is no need for explicit implements declarations to make them compatible.
This structural approach has limits. When two shapes are accidentally compatible — when a UserId and an OrderId are both string — TypeScript will not catch a mix-up between them unless the types are made structurally distinct (using branded or opaque types). Developers coming from nominal-typed languages sometimes expect type names to carry safety that only structural distinctiveness provides.
The cost of adopting TypeScript scales with delay
Retrofitting TypeScript onto an existing JavaScript codebase requires touching every file. Each file needs type annotations added and type errors resolved before TypeScript accepts it. Teams that delay adoption until the codebase is large face a migration that takes weeks, introduces any annotations as escape hatches to make the build pass quickly, and produces incomplete coverage until those escapes are resolved — which, under the pressure of ongoing feature work, often means they are never resolved.
Starting with TypeScript costs one afternoon of configuration. A new project needs a tsconfig.json, a compilation step in the build pipeline, and a decision about whether to use TypeScript files directly (with ts-node, tsx, or a bundler that handles TypeScript) or to compile to a separate output directory. That configuration is stable and does not need to change as the project grows. Every file added to the project is typed from the start; no retrofit is ever required.
The migration cost is not linear. A 10-file JavaScript project can be migrated to TypeScript in a day. A 300-file project takes weeks. A 1,000-file project may require a formal migration project with dedicated resources. The longer TypeScript adoption is deferred, the more the migration cost grows relative to the benefit.
TypeScript is not a substitute for runtime validation
TypeScript types are erased at compile time. The compiled JavaScript contains no type information — no checks, no assertions, no guards. An API response typed as User is not validated as User at runtime; it is trusted as User. If the API returns a null where User is expected, TypeScript does not catch this. The type annotation expresses the developer's expectation; it does not enforce it.
Data from external sources — API responses, localStorage values, URL parameters, form inputs, environment variables — must be validated at runtime with a schema library. Zod, Valibot, and similar libraries provide a mechanism to parse untyped data and produce a typed result if the data matches the expected shape, or throw a descriptive error if it does not. The schema serves as both a runtime validator and a TypeScript type source; the two cannot get out of sync because the type is derived from the schema.
This distinction is one of the most common misunderstandings in TypeScript adoption. Developers who expect TypeScript to prevent runtime errors caused by unexpected API shapes or malformed inputs will be surprised when those errors occur. TypeScript prevents errors in code that the developer writes; it does not prevent errors caused by data the code receives. This distinction is covered in depth in FEE-1708.
Best Practices
MUST add TypeScript to new projects from day one, not retrofit it after the codebase grows. Retrofitting TypeScript requires touching every file to add type annotations and resolve errors. Teams that defer adoption until the codebase is large face a multi-week migration that produces any annotations as escape hatches — annotations that persist long after the migration is nominally complete, leaving silent gaps in type coverage. The configuration cost of TypeScript at project start is low; the migration cost grows proportionally with codebase size.
MUST enable the strict flag in tsconfig.json at project initialization. Strict mode activates noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, and several additional checks — see the tsconfig reference for the complete list. The cost of resolving strict-mode errors is low when the codebase is small. Enabling strict mode after the codebase grows requires fixing hundreds of pre-existing errors and produces a prolonged broken-build state. Enabling individual strict flags without the umbrella strict flag also risks missing new strict checks added in future TypeScript versions.
MUST NOT use @ts-ignore without a comment explaining the reason and the conditions under which it can be removed. A bare @ts-ignore suppresses the type error and removes all record of why. When the underlying issue is resolved upstream — a library ships its own types, a structural change makes the cast unnecessary — the directive remains indefinitely, invisibly widening the type safety gap. Every suppression directive is technical debt; treating it as such means documenting it.
SHOULD measure TypeScript adoption quality by the rate of type-related runtime errors in production, not by type coverage percentage. Type coverage tools measure how much of the codebase has explicit type annotations, but a codebase with 95% coverage and liberal any usage can have worse type safety than one with 80% coverage and strict mode enabled. Production error rates caused by property-does-not-exist or cannot-read-property-of-undefined errors are the signal that TypeScript is meant to eliminate.
Related FEEs
- FEE-301 — Event Loop & Async Model (TypeScript's async/await types build on the runtime model)
- FEE-1701 — Type System Fundamentals & Type Inference
- FEE-1702 — Generics
- FEE-1703 — Utility Types & Type Manipulation
- FEE-1704 — Narrowing & Type Guards
- FEE-1706 — tsconfig & Strict Mode
- FEE-1707 — TypeScript in React
- FEE-1708 — Runtime Validation & Schema Libraries