TypeScript

The typechecker is the fastest reviewer on the team. Let it run.

2guides Feed

TypeScript’s practical value is not the type annotations. It is having a verifier that reads every call site in the project in a few seconds, which is a capability no amount of code review provides.

That framing decides what to optimise for: making the typechecker fast enough to run constantly, and making sure it is checking the same thing the build does.

Incremental compilation is the first lever. Setting incremental with a tsBuildInfoFile takes repeat tsc --noEmit runs on a mid-sized project from tens of seconds to a couple. On a monorepo, project references extend the same idea across packages. Both matter more once tooling — a pre-commit hook, an editor, a coding agent — is running the check on every edit.

The gap that catches people is between tsc and the bundler. They resolve modules differently, particularly with paths aliases and package exports fields, so a green typecheck and a failing build are entirely compatible states. Run both.

The other recurring problem is at the boundaries. A type assertion on a fetch response or on process.env is a claim about data you did not check, and it will be wrong eventually. Validate at the boundary with a schema library and infer the static type from the validator, so there is one definition rather than two that drift apart.

Coverage here is applied rather than encyclopaedic: configuration that changes how a project behaves, and the places where the type system’s guarantees stop.

Start here

How to Use Claude Code on an Existing TypeScript Project

Add Claude Code to a TypeScript repo you already have: a CLAUDE.md that matches your real build, permission rules that block dangerous commands, and a typecheck loop the agent runs itself.

Intermediate · 5 min read

Beginner to advanced

A reading order that builds TypeScript knowledge in the sequence it is actually needed.

  1. Build How to Use Claude Code on an Existing TypeScript Project 5 min

Common problems

Failure modes that come up repeatedly with TypeScript, and where each one is solved.

Typecheck passes but the build fails
`tsc --noEmit` and your bundler do not always resolve modules the same way, particularly with path aliases. Run both before calling a change done.
tsc is too slow to run on every change
Turn on `incremental` and set `tsBuildInfoFile` so repeat runs reuse the previous program. On large repos, use project references as well.
Types drift from runtime behaviour at the boundaries
Type assertions on API responses and environment variables are claims, not checks. Validate at the boundary and infer the type from the validator.

Latest TypeScript guides

Browse the archive
  • intermediate

    How to Deploy an Astro Site to Cloudflare Workers

    Ship a static or server-rendered Astro site to Cloudflare Workers with Wrangler — adapter setup, wrangler.jsonc, nodejs_compat, secrets, custom domains and the errors you hit on the first deploy.

    4 min

Recently updated

  • intermediate

    How to Deploy an Astro Site to Cloudflare Workers

    Ship a static or server-rendered Astro site to Cloudflare Workers with Wrangler — adapter setup, wrangler.jsonc, nodejs_compat, secrets, custom domains and the errors you hit on the first deploy.

    4 min

Frequently asked questions

Is strict mode worth enabling on an existing project?

Yes, but incrementally. Turn on individual flags — `noImplicitAny` first, then `strictNullChecks` — and fix each wave. Enabling all of strict at once on a large codebase produces a error list nobody works through.

Should types be validated at runtime?

At every boundary the compiler cannot see: HTTP responses, environment variables, parsed JSON, database rows from an untyped driver. Inside those boundaries, the types are enough.

Does the typechecker replace tests?

It replaces a category of test — the ones asserting that a function is called with the right shape. It says nothing about whether the behaviour is correct, which is what the remaining tests are for.

Sources

  1. TypeScript handbook Microsoft Primary source
  2. tsconfig reference Microsoft Primary source