TypeScript: Complete Guide

TypeScript is JavaScript with a checker in front of it. You write down what your data should look like, and your editor flags the code the moment it drifts away from that shape. What ships to the browser is still plain JavaScript.

If you are still weighing it against the plain language, the JavaScript vs TypeScript comparison compares their benefits and trade-offs.

TypeScript at a Glance

The live part of this section splits into three topics, roughly in the order most people meet them.

Area	What it covers	Start here if
Types	Annotations, interfaces, unions, runtime data	You are writing your first TypeScript
Generics	Function types, type parameters, utility types	You keep repeating the same shapes
Tooling	tsconfig.json, checking, React, API contracts	The build or the config fights you

What Is TypeScript, in Plain Words?

TypeScript is a programming language that Microsoft announced on 1 October 2012. The team built it for what they called JavaScript development at application scale, meaning code bases big enough that nobody can hold them in their head anymore, and it adds one big thing to JavaScript, which is a static type checker.

A type describes the shape of a value, like "a user has an id and an email, and the email is always text." An annotation is where you write that shape down. Inference is the checker working out a shape on its own when you did not write one.

Picture a building inspector who reads the plans before anyone pours concrete. Finding the missing doorway on paper costs you an eraser, while finding it after the walls are up costs you a sledgehammer. TypeScript reads your files before anything runs, and it reports every place where the code disagrees with the shapes you stated.

One rule sits under everything else on this page. Types exist while you work and disappear before the code runs, so browsers and Node only ever execute JavaScript. A type therefore cannot vouch for data that arrives while the program is running, like a server response or a form submission (the two places bad data usually walks in), and those still need a real check. The unknown, any, and runtime data guide shows how.

Why Would You Use TypeScript, and Does It Pay Off?

TypeScript earns its keep where code has real boundaries. A boundary is any place where data crosses from one part of the program to another: an API response, a database row, a React prop, a command-line flag, or a function that three different files call.

It costs you a check step, some configuration (a tsconfig.json file, mostly), and a little more to read in every file. The table lists what you get for that price.

Area	You get	You pay
Mistakes	Typos and wrong shapes caught early	A check step to keep running
Editor	Autocomplete and safer renames	A config file to learn
Teamwork	Shapes written down for readers	More text in every file
AI output	A mechanical first reviewer	False comfort when any creeps in

The catch is that types only help when they are honest. A project full of any, oversized object shapes, and forced assertions turns the checker into decoration, and decoration does not catch bugs.

Should I Learn TypeScript or JavaScript First?

Learn plain JavaScript first, and add TypeScript when the project asks for it. TypeScript sits on top of JavaScript behavior, so closures, promises, objects, and arrays all still apply, and learning both at once hides which half is causing your problem. I'd move to TypeScript once arrays, objects, and functions feel natural, or once a project grows past a few files.

Most beginners seem to agree with that order. In the 2025 Stack Overflow Developer Survey, 62.8% of people learning to code used JavaScript and 31.9% used TypeScript.

Your situation	Start with	Why
Brand new to code	JavaScript	Fewer moving parts to untangle
Comfortable with objects and functions	Add TypeScript	Your shapes finally have names
Joining a team that uses it	TypeScript, JavaScript beside it	The config already exists
Know Java, C#, or Swift	Either one	The type ideas look familiar

Our JavaScript guide covers the language underneath, and the comparison page takes the full side-by-side.

Do I Need TypeScript for a Small Project?

A small project does not need it. A throwaway script, a prototype, or a one-page site is fine in plain JavaScript, and that is often the right call. The math changes once a project keeps changing and other people have to touch it.

Project	TypeScript?	Reason
One-file script	Skip it	You can hold it in your head
Small personal site	Optional	Editor help may be enough
App with an API	Yes	Data shapes cross many files
Library other people install	Yes	Types double as documentation

Small does not have to mean untyped, though.

Node can now run a TypeScript file directly, which removes most of the setup that used to make TypeScript feel heavy for a tiny project. The Node section below explains what that does and does not give you.

What Is TypeScript Used for, and Who Uses It?

It shows up wherever a JavaScript code base has grown past what one person can remember. Typical homes are front ends with shared component props and server data, full-stack apps where route handlers and screens share models, libraries and SDKs other developers install, and backend services with request and job payloads.

Company posts show why teams make the move. Slack wrote in 2017 that porting its desktop app surprised the team with the number of small bugs it found, and that the editor suddenly knew which properties and methods each object had. Stripe moved more than 3.7 million lines of code from Flow to TypeScript in one pull request on 6 March 2022. Its post says Flow's memory use could lock up laptops, and that the in-editor integration was frequently slow and unreliable.

Those are two big teams with big code bases, and your project might not look like either. The survey gives the wider picture. TypeScript was used by 43.6% of all respondents in 2025 and 48.8% of professional developers.

Is TypeScript Still Growing, and Where Did It Start?

TypeScript started as a Microsoft project in 2012, and the numbers now say it is growing very fast. GitHub's Octoverse report for 2025 says that in August 2025 TypeScript became the most used language on GitHub by contributor count, passing Python by roughly 42,000 contributors. It gained over a million contributors in a year, a 66% jump, while JavaScript grew 24.79% over the same period.

GitHub gives two reasons for the jump in its report. Nearly every major frontend framework now scaffolds new projects with TypeScript by default, and typed languages make agent-assisted coding more reliable. Treat the ranking as a contributor count rather than a job-market measure, because contributors are not hours coded or jobs posted.

The compiler itself changed this year, and that matters for older advice. The team said TypeScript 6.0, released in March 2026, was meant to be the last release built on the original JavaScript code base. The team's TypeScript 7.0 announcement, published on 8 July 2026, describes a native port written in Go with speedups between 8x and 12x on full builds.

So any tutorial that tells you to live with slow type checking predates that rewrite, and I'd treat it as dated advice. The announcement also says 7.0 ships without a programmatic API and that the team expects 7.1 to bring a new one. It names Vue, MDX, Astro, Svelte, and Angular template checking as tools that embed TypeScript and will likely stay on 6.0 until then. The tooling topic is where the compiler and its settings live.

Is TypeScript Hard to Learn?

The first layer of TypeScript is gentle and quick to pick up. You name a shape, you fix the red squiggle, and your editor starts finishing your sentences. Most people are productive in that layer quickly (and yes, the squiggles are annoying at first, I get it).

The second layer is where people stall, because generics and utility types look like algebra. Skip them until you catch yourself copying the same helper for users, then orders, then invoices.

The third layer, conditional and mapped types, is powerful and rarely where your first month of value lives.

Layer	Learn it when	Guide
Annotations and unions	You write your first typed file	First types
Generics and utility types	The same helper keeps getting copied	Generics topic

Compiler error messages are the other hard part, since they can run to several lines. Reading them gets much easier once the shapes in the types topic feel familiar.

Is TypeScript Worth It with AI Agents Writing Code?

Yes, and the case is stronger than it was two years ago. An agent can produce typed-looking code in seconds, which is exactly why you want something mechanical checking it. GitHub's Octoverse report cites a 2025 academic study finding that 94% of LLM-generated compilation errors were type-check failures, meaning the checker is aimed at the most common way generated code breaks.

It will not do the review for you. In the 2025 Stack Overflow survey, 84% of respondents were using or planning to use AI tools, yet 46% said they distrust the accuracy of the output and only 33% trust it. The biggest single frustration, at 66%, was answers that are almost right but not quite.

What I like about types in that setup is that they turn "almost right" into a red line you can see. What I'd never rely on is a green check as proof, since a compile pass says nothing about whether the function computes the right answer.

Here is how to work with an assistant so the types do their job.

• Name the types before you ask for the code: give it the data shape, the allowed states, the runtime boundary, and the strictness you are working under.
• Read the type model first and the implementation second, because mushy types usually mean a mushy function.
• Hunt for any where unknown or a union belongs, and for optional fields standing in for states that should be modeled.
• Distrust as SomeType on parsed data, since an assertion is a promise and not a validation.
• Compare response types with the backend code, because hand-copied ones start drifting on day one.

The best AI-generated TypeScript tends to have boring types, and boring is the compliment. For the labor-market side of whether to learn to code at all, our should you learn to code article has the numbers, and the AI coding tools hub covers which assistants to try.

Can I Run TypeScript in Node Now that Node Strips Types?

Yes, you can, though Node only handles part of the job. Node's own documentation says it will execute TypeScript files that contain only erasable syntax, meaning syntax it can remove without rewriting anything.

Type stripping has been on by default since Node 22.18 and 23.6, and it is marked stable from 24.12 and 25.2.

Job	Who does it	Note
Run a .ts file	Node, by stripping types	No build step for erasable code
Check your types	tsc or your editor	Node never checks types
Use enums or decorators	Not Node's stripping mode	Node reports an error
Apply tsconfig.json settings	tsc only	Node ignores that file

Node documents the unsupported pieces as enum declarations, namespaces that hold runtime code, parameter properties, import aliases, and decorators. Everything else is just types being deleted. That makes Node great for scripts, tools, and small projects, and it means a clean run proves nothing about your types. Keep a separate tsc --noEmit step for that.

Deno and Bun also run .ts files directly, going by their own documentation, and browsers still need plain JavaScript, so something has to remove the types before a page ships.

The Node topic covers running files and projects, and the compiler side lives in the project workflow guide.

Should I Pick TypeScript or Another Language for This Job?

Pick the language by the job in front of you. TypeScript is the natural fit when a screen is involved and you already know JavaScript, and other languages win on specific jobs.

Job	Strong pick	Why
Browser interface	TypeScript	Browsers run JavaScript only
API next to that interface	TypeScript	One language, shared models
Simple, fast backend service	Go	Easy deploys, built-in concurrency
Data or machine learning	Python	The tooling is Python-first
Memory-critical systems code	Rust	Safety without a garbage collector
Teams already on .NET	C#	Mature platform and tooling

My call: if you know JavaScript and the project has a screen, stay in TypeScript. Look at Go, Python, Rust, or C# when the job leans toward their strengths.

What Mistakes Do Beginners Make with TypeScript?

Four mistakes come up again and again, and people usually blame the language for them when the model underneath is the real problem.

• Treating the compiler as a linter to appease: an error usually means the model is unclear, and a better type or a simpler function often fixes it where another annotation will not.
• Reaching for as instead of a check: an assertion is a promise and not a validation, as the runtime data guide shows.
• Making every property optional: a pile of ? fields hides which combinations are legal, and discriminated unions name the states instead.
• Letting a shared types file become a dumping ground: keep types near the code they describe until they are really shared, a line the interfaces and aliases guide draws.

What Can't TypeScript Do?

TypeScript does not validate values that arrive at runtime. Your program can run its own checks and validators, but TypeScript will not do it for you, so network responses, form input, and environment variables need code you write.

It cannot rescue a bad model, since a type can describe a confusing domain perfectly and the domain stays confusing. It does not replace tests, because type checking confirms that shapes fit under your config and says nothing about whether a function gets the right answer.

It also gives you no security boundary at all. Anything crossing the wire is untrusted however it is typed, which is why application security treats the client as hostile input.

Where Do I Go Next? Every Guide Under This Page

Each group below starts from the problem you are probably having, then lists the guides that fix it in reading order.

The Type System

Start here if values keep arriving in a shape your code did not expect. The four guides build on each other, and the types topic holds them together.

• The First Types to Learn: primitive annotations, arrays, object types, and where inference already knows the answer.
• Interfaces and Type Aliases: what each form can express, extension, declaration merging, and which one to default to.
• Union Types and Narrowing: literal types, the narrowing toolkit, discriminated unions, and exhaustiveness with never.
• unknown, any, and Runtime Data: when unknown is the right starting type at a boundary, how to validate parsed JSON, and what an assertion really costs.

Reusable Types and Generics

Start here if you wrote the same function for three different shapes. These guides are about naming a shape once and reusing it, and the generics topic shows how they connect.

• Typing Functions and Callbacks: parameters, return types, optional and rest parameters, and the contextual typing that saves the annotation.
• Generic Functions and Types: type parameters, inference at the call site, constraints with extends, and defaults.
• Utility Types: Pick, Omit, Partial, Record, ReturnType, and when a named type beats a clever one.

Configuration and Tooling

Start here if your editor is green and your pipeline is red. This is the half of TypeScript that sits outside the type system: the compiler, the config file, and two contexts with typing rules of their own, React components and API contracts. All four guides sit under the tooling topic.

• tsconfig.json Explained: which files get checked, what strict turns on, the flags that stay off until you name them, and sharing a config.
• Tooling and Project Workflow: the compiler commands, why transpiling and type checking are separate jobs, a real check in CI, and migrating a JavaScript codebase.
• TypeScript with React: JSX settings, prop types, typed state and refs, event handlers, and the server and client boundary.
• API Contracts and Shared Models: modeling a request and response once, generating types from a schema, and why validation stays a separate step.

What Should I Learn First?

Learn it in roughly the order you will use it at work.

1. Get comfortable with JavaScript first: objects, arrays, modules, promises, and closures.
2. Learn annotations, inference, object types, and function signatures.
3. Learn unions and narrowing before you go near generics.
4. Add generics and utility types once duplication actually appears.
5. Read tsconfig.json until the main strictness settings make sense.
6. Apply all of it to React props, API clients, and server data.

Skip advanced type gymnastics until something forces the issue. Conditional types, mapped types, and template literal types are powerful, and they are rarely where the first month of value lives.

Which Languages and Comparisons Sit Next to TypeScript?

• JavaScript vs TypeScript: the full side-by-side, if you are still weighing whether types are worth the step.
• JavaScript: the runtime model TypeScript compiles down to and never replaces.
• Frontend development: the order to learn HTML, CSS, and JavaScript before you add types.
• Go: a typed backend language when deployment simplicity and concurrency matter more than the browser.
• Rust: a stricter compiler still, when memory safety and low-level control are part of the job.
• C#: a mature managed platform when .NET, ASP.NET Core, and enterprise tooling are the environment.
• Programming: the wider language index, including the data and database guides.

Frequently Asked Questions

Is TypeScript replacing JavaScript?

No. TypeScript compiles to JavaScript and runs on the same engines, so it is a layer over the language rather than a successor. A browser build ships JavaScript once the types are removed, though some projects only type-check with noEmit, emit declarations alone, or run .ts files directly in Node, Deno, or Bun.

Do you need to learn JavaScript before TypeScript?

You need the JavaScript fundamentals at the very least. TypeScript adds a type layer on top of JavaScript semantics, so closures, asynchronous behavior, and the way objects and arrays actually work still apply. Learning both at once tends to hide which half is causing a problem.

Does TypeScript make code run slower?

No. The type layer is erased during compilation, so annotations and interfaces add nothing to the shipped JavaScript. Some compiler options do change the output, such as an older target that downlevels syntax or adds helpers, but the everyday cost of type checking lands at build time and in the editor.

What are .d.ts declaration files for?

They describe the shape of code without containing it, so TypeScript can check calls into plain JavaScript libraries, built-ins, and published TypeScript APIs. Many packages ship their own declarations alongside the code. For untyped packages, community definitions often live under npm's @types scope, and where none exists you write the declarations yourself.

Which section should you start with?

Types, unless you already write annotations comfortably. Generics only pays off once you are repeating the same shapes, and tooling makes more sense after strict-mode errors are readable. The at-a-glance table above routes each case.

Is TypeScript harder than JavaScript?

It is more to learn, because you pick up the type layer after the language. The first layer of annotations is gentle, while generics and conditional types take longer. Most beginners do fine by learning JavaScript first and adding types when a project starts to need them.

Should you learn TypeScript or Python first?

Pick by what you want to build. TypeScript fits browser interfaces and full-stack web work, while Python fits scripting, data, and machine learning. If you pick TypeScript, learn plain JavaScript first, since the types sit on top of it.

Do AI coding agents make TypeScript unnecessary?

No. Agents write TypeScript fluently, and the type checker is a cheap first reviewer of what they produce. GitHub's 2025 Octoverse report links TypeScript's rise to typed languages making agent-assisted coding more reliable. You still have to read the types and run real tests.

Where to Start

Build one small thing with real state: a task list, a settings page, or an admin table. Give it a nullable field, a load state modeled as a union, and one API call validated at the boundary. Work through the first types to learn if annotations are new, then unions and narrowing.