Type Annotations and Inference
How to write explicit type annotations and when to rely on TypeScript's type inference.
What you'll learn
- How to write explicit type annotations with the colon syntax
- When TypeScript infers types automatically
- Why explicit annotations matter for function signatures
- The difference between annotation and assertion
Concept
Explicit Annotations
A type annotation uses a colon to declare a variable's type: let count: number = 0 or function greet(name: string): string. Annotations are optional in many cases but valuable for function parameters (which have no inference context) and return types on public APIs. Explicit annotations serve as documentation and catch mistakes when a refactor changes the inferred type.
Type Inference
TypeScript can infer types without annotations. If you write let count = 0, TypeScript infers number. If you write const greeting = "hi", it infers the literal type "hi". Inference is powerful — you should let it work for local variables and only annotate where it adds clarity or safety. Over-annotating makes code verbose without adding value.
Annotations vs Assertions
An annotation (let x: string = y) checks that y is assignable to string. A type assertion (let x = y as string) tells the compiler "trust me, this is a string" without checking. Assertions bypass the compiler's safety and should be used sparingly — typically when you know more than the compiler, like parsing unknown data from an API.
Example
// Explicit annotation — the compiler verifies the value matches.
let itemCount: number = 42;
let label: string = "Products";
// Inference — TypeScript figures out the type automatically.
let total = 100; // inferred as number
let message = "Hello"; // inferred as string
let items = [1, 2, 3]; // inferred as number[]
// Function parameters NEED annotations (no inference context).
function calculateTotal(price: number, qty: number): number {
return price * qty;
}
// Type assertion — use sparingly, it bypasses checking.
let data: unknown = "12345";
let length = (data as string).length;
Annotate function parameters and public return types. Let inference handle local variables. Use assertions (as) only when you truly know better than the compiler.
Try it
- JSON to TypeScript
See how inferred shapes become explicit annotations.
- Code Diff
Compare annotated and inferred versions of the same code.
Common mistakes
The mistake
Using type assertions (as) instead of annotations to fix errors
The fix
Assertions silence the compiler without checking. Use them only for genuinely unknown data. Prefer proper annotations or type guards.
The mistake
Annotating every local variable when inference would work
The fix
Let TypeScript infer types for simple local variables. Annotate function signatures, public APIs, and places where the inferred type is too broad.
Practice Type Annotations and Inference
10 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.