Learn TypeScript

Where TypeScript is used

Large front-end applications

Angular is written in and for TypeScript, and most sizeable React and Vue codebases use it, because types are what let a team change one part of a big application without breaking another.

Node.js back ends

Servers and APIs written for Node.js are commonly TypeScript, giving request handlers and database calls checked shapes rather than loose objects.

Libraries and developer tools

Many published npm packages are written in TypeScript or ship type declarations, and a good deal of the tooling around web development — editors, linters, build tools — is TypeScript itself.

Anywhere JavaScript runs

Because the output is JavaScript, TypeScript covers browser extensions, desktop apps and serverless functions without changing how any of those are deployed.

Your first TypeScript program

Saved as hello.ts. You can paste it straight into the playground to see it run.

type Score = { name: string; points: number };
const scores: Score[] = [
  { name: "Asha", points: 88 },
  { name: "Ben", points: 95 },
];
for (const score of scores) {
  console.log(`${score.name} scored ${score.points} points.`);
}

What it prints

Asha scored 88 points.
Ben scored 95 points.

1. Line 1 declares a type called Score: an object with a name that must be a string and a points that must be a number. Types like this are checked by the compiler and disappear from the output JavaScript.
2. Lines 2 to 5 create an array of two such objects. The annotation Score[] tells the compiler that every element must fit the Score shape; misspell points in one of them and it refuses to compile.
3. Line 6 starts a for...of loop that takes each object in turn and calls it score. Because the array is typed, the compiler knows score is a Score without being told.
4. Line 7 prints a template literal — the backticks let ${...} drop values into text. Your editor can autocomplete score.name and score.points here, and would flag score.point with a compile error.
5. Line 8 closes the loop. Nothing in this program is checked while it runs; all of the checking happened before the JavaScript was produced.

Try it in the TypeScript playground →

Run TypeScript on your own computer

TypeScript needs Node.js plus one extra tool: the compiler, tsc, which turns .ts files into .js files. Newer Node.js releases can also run a .ts file directly, which is handy for quick experiments.

1. 1

   Install Node.js

   Download the current LTS release from nodejs.org and run the installer. This gives you node and npm, and TypeScript is installed with npm.

2. 2

   Install the TypeScript compiler

   This puts the tsc command on your PATH. In a real project you would instead add it to that project with npm install --save-dev typescript, but a global install is fine for learning. Confirm it with tsc --version.

   Shell

   npm install -g typescript

3. 3

   Compile the program

   Save the code above as hello.ts and compile it. Type errors are printed here with a line number; if there are none, a hello.js file appears next to the source.

   Shell

   tsc hello.ts

4. 4

   Run the JavaScript

   The compiled file is ordinary JavaScript with the types stripped out, and Node runs it like any other.

   Shell

   node hello.js

5. 5

   Or skip the compile step

   tsx runs a TypeScript file in one command (npx downloads it the first time). Node.js 23.6 and later can also run node hello.ts directly by stripping the type annotations. Both are convenient, but neither checks your types — only tsc does that, so keep it in the loop.

   Shell

   npx tsx hello.ts

6. 6

   Set up a project properly

   Once you have more than one file, run this in the project folder to create tsconfig.json. Keep strict enabled; it is what makes the compiler catch null and undefined mistakes.

   Shell

   tsc --init

A learning order for TypeScript

Stages, not a timetable. Each one exists because the next would not make sense without it, and how long each takes depends on how much you write.

1. Stage 1. The JavaScript underneath

   • let and const
   • functions and arrow functions
   • arrays and objects
   • loops and conditions
   • template literals

   TypeScript adds types to JavaScript; it does not replace it. Every error the compiler reports is about a JavaScript value, so you need the values first.

2. Stage 2. Basic annotations and inference

   • string, number and boolean
   • typed arrays
   • parameter and return types
   • type inference
   • any versus unknown

   Most of the benefit comes from annotating function boundaries and letting the compiler infer the rest. Learning when not to annotate is as important as learning how.

3. Stage 3. Describing shapes

   • type aliases and interfaces
   • optional and readonly properties
   • union and literal types
   • narrowing with typeof, in and equality checks
   • null and undefined under strict mode

   Real data is objects with optional fields and values that might be missing. This is where TypeScript starts catching the bugs JavaScript would only reveal in production.

4. Stage 4. Generics and reuse

   • generic functions
   • generic types and constraints
   • keyof and indexed access
   • utility types: Partial, Pick and Record
   • type assertions and when to avoid them

   Generics let one function or type work for many kinds of value without giving up checking. They also account for most of the confusing error messages, so they are worth a slow pass.

5. Stage 5. The compiler and real projects

   • tsconfig.json and strict
   • reading compiler errors
   • ES modules
   • declaration files and @types packages
   • TypeScript with a framework or Node.js

   A project is where configuration, third-party types and build steps meet. Understanding tsconfig once saves hours of puzzling later.

6. Stage 6. Patterns for larger code

   • classes and access modifiers
   • async / await with typed results
   • discriminated unions and exhaustive checks
   • testing
   • a project of your own

   These are the patterns that make bigger TypeScript codebases pleasant to work in. By this point the compiler feels like a collaborator rather than an obstacle.

Mistakes beginners make in TypeScript

Reaching for any to make an error go away

any switches checking off for that value and everything derived from it, so the mistake the compiler found is still there, just hidden. If the type genuinely is not known, use unknown and narrow it with a check; if it is known, write it down.

Ignoring 'Object is possibly undefined'

error TS2532: Object is possibly 'undefined' (or TS18047 for null) means the compiler can see a path where the value is missing — an array lookup, an optional property, a find() that may fail. The fix is a check such as if (item) { ... } or optional chaining with item?.name, not a non-null assertion (the exclamation mark after a value), which just tells the compiler to trust you.

Expecting types to exist at run time

Types are erased when the code is compiled, so you cannot test them while the program runs. Writing value instanceof Score for a type alias gives error TS2693: 'Score' only refers to a type, but is being used as a value here. Data from a JSON response is not checked either — the compiler trusts whatever type you claimed. Validate it yourself at the edge and keep the type for the inside.

Misreading 'Property does not exist on type'

error TS2339: Property 'point' does not exist on type 'Score' is usually one of two things: a typo (the compiler often adds Did you mean 'points'?), or the property really is missing from the type you declared even though the object has it at run time. If the property is real, fix the type, not the code that uses it.

Treating as like a conversion

"42" as number does not turn text into a number; it is refused with error TS2352 because the types do not overlap, and even response as User only tells the compiler to stop checking. Convert with Number() or a proper parse, and reserve as for the rare cases where you know more than the compiler does.

Strengths and trade-offs

Who TypeScript is for

TypeScript is the right next language for anyone who knows some JavaScript and is building anything that will grow past a few files, involve other people or run for a long time. It is also the sensible choice if you are coming from Java, C# or another statically typed language and want the web without giving up the compiler. It is a less ideal first language: the type errors only mean something once you understand the JavaScript values underneath, so begin with plain JavaScript through functions and objects and then switch. If your interest is data science, game engines or native mobile apps, the advice is the same as for JavaScript — look at Python, C++, or Swift and Kotlin instead.

Questions about learning TypeScript

Do I have to learn JavaScript before TypeScript?

Mostly, yes. TypeScript is a superset: every valid JavaScript program is a TypeScript program, and the run-time behaviour comes entirely from JavaScript. You can learn them together, but if the compiler says a value might be undefined, you need to know what undefined is. Learners who already write JavaScript usually find the switch straightforward.

Does TypeScript make my code faster?

No. The types are removed during compilation and the JavaScript that runs is the same as you would have written by hand. What it changes is how many bugs reach the running program, and how safely you can change code later.

Can browsers run TypeScript directly?

No. Browsers only understand JavaScript, so a .ts file must be compiled first, either by tsc or by a bundler that does it for you. Node.js from version 23.6 can strip the types and run a .ts file, but it does not check them, so tsc remains part of the workflow.

Should I use type or interface?

Either. Both describe the shape of an object, and for most everyday code they are interchangeable. An interface can be extended by another interface and is often preferred for object shapes; a type alias can also name unions, tuples and primitives, which an interface cannot. Pick one style for objects, stay consistent, and use type for everything that is not an object shape.

The primary source

When this guide and the official documentation disagree, the documentation is right and we would like to hear about it.

• The TypeScript Handbook ↗
• TypeScript for JavaScript programmers ↗
• Download TypeScript ↗