TypeScript Tooling

Types are only half of TypeScript. The other half is the configuration and tooling that decide which files are checked, how strictly, what JavaScript comes out the other end, and whether anything is checking at all. This topic covers that half, then applies it to the two places most projects meet it: React components and the contracts between a frontend and its API.

The four guides below are ordered by dependency rather than difficulty. tsconfig.json comes first because every later flag reference points back to it.

TypeScript Tooling Topics

• tsconfig.json covers what the file controls, what strict actually turns on, and the individual flags worth knowing by name.
• Tooling and Project Workflow covers tsc, the language service, the transpile-versus-check split, CI, and gradual migration from JavaScript.
• TypeScript with React covers prop types, hooks, event handlers, and the server and client boundary in full-stack frameworks.
• API Contracts and Shared Models covers modelling requests and responses once, generating types from a source of truth, and why validation is still a separate step.

The Rule Everything Here Depends On

Compiling and type checking are two different jobs, and most modern setups split them apart. Understanding that split explains nearly every confusing tooling result you will hit:

# checks types, writes no output
tsc --noEmit

# strips types fast, checks nothing
esbuild src/index.ts --outfile=dist/index.js

The first command is the type checker. The second is a transpiler: it removes the annotations file by file and emits JavaScript while doing no semantic checking at all, and complete checking also needs information from other files. Both produce working output, but only one of them can tell you the code is wrong.

This is why a project can ship a bug the compiler would have caught. The dev server was happy, the build passed, and nothing in the pipeline ever ran a checker. Some frameworks add a checking step of their own, and some deliberately leave it to you, so the honest move is to check your own setup rather than assume. If nothing checks, add a tsc --noEmit job and let it fail the build.

Type checking is static rather than something that happens while your code runs. It works in your editor as you type, in CI, and in a build step, but no flag in tsconfig.json validates a JSON response or a form submission, because the annotations are gone before that data arrives.

How the Four Guides Fit Together

The tsconfig guide sets the rules. Whether an unchecked parameter is an error, whether items[0] might be undefined, and whether JSX compiles at all are all decisions in that file, and the other three guides assume you made them deliberately.

The workflow guide covers the commands and habits around those rules: running the checker, wiring it into CI, understanding why your editor and your build sometimes disagree, and migrating an existing JavaScript codebase without stalling halfway.

The last two guides apply the rules to real boundaries. React props are a boundary between components, and an API response is a boundary between systems. The React guide is mostly about naming shapes precisely; the API contracts guide is mostly about not trusting shapes you did not produce.

Matching the Guides to Your Setup

Which of these four guides matters most depends on what you are building. The same setting carries different weight in a library, a service, and a bundled app, so start where your own project actually lives.

• A bundled frontend app built with Vite, Next.js, or Astro: the bundler produces the JavaScript, so the strictness settings matter more to you than the emit ones. Read tsconfig.json, then use the workflow guide to find out whether anything in your pipeline checks types at all.
• A Node service: for a service emitted by tsc, module, module-resolution, and target settings govern TypeScript's checking and output, which puts tsconfig.json first. If Node runs the TypeScript directly, it ignores tsconfig.json during execution, and the workflow guide covers running files and wiring up CI.
• A shared library: the declaration files you emit are what every consumer reads, so emit settings stop being an internal detail. The tsconfig guide covers them, and API Contracts and Shared Models covers publishing a shape other code depends on.
• An existing JavaScript codebase: the migration material in the workflow guide comes before anything else, because raising strictness is something you do gradually rather than on day one.
• A React frontend talking to an API: once the config is settled, TypeScript with React and API Contracts and Shared Models are the two pages that describe your daily work.

What to Decide First on a New Project

Three decisions come early, and each one is cheaper now than later.

First, whether strict is on. Switching it on at the start costs almost nothing, while switching it on a year in usually means reading a wall of diagnostics in one sitting.

Second, what runs the check. If your build only strips types, decide where the checking step lives before the codebase quietly grows to depend on nothing checking it.

Third, where the types for outside data come from. Hand-written interfaces and types generated from a schema both work, and the API contracts guide covers the trade between them. Neither one removes the need for a runtime check.

Common Pitfalls

• Disabling a flag only to silence an error without understanding the guarantee being removed: turning individual flags off is a supported choice, and the problem is making it blind. The tsconfig guide covers what each strictness flag is actually claiming about your code.
• Assuming a green build means checked types: many pipelines transpile without checking. The workflow guide covers how to tell and what to add.
• Copying a tsconfig.json between project types: a library, a Node service, and a bundled frontend app have different module and emit needs. The tsconfig guide separates the strictness settings, which travel well, from the module settings, which do not.
• Passing whole database rows into components: a component prop should be the narrow shape the UI needs. The React guide covers the adapter pattern that keeps them separate.
• Treating a shared response type as validation: it is a claim about the server, not a check on it. The API contracts guide covers the difference.

Common Questions

Does my build tool already check types?

Often not. Transpilers such as esbuild, SWC, and Babel strip type annotations per file without checking them, which is what makes them fast. Frameworks differ on whether they add a checking step, so confirm your own setup and keep a tsc --noEmit run in CI if nothing else performs one.

Which guide should you read first?

Read the tsconfig guide first, because every other guide in this topic assumes flags such as strict and jsx are already set the way you want. Tooling and project workflow follows naturally, then React and API contracts as your project needs them.

Does turning on strict break an existing project?

Usually it produces new diagnostics rather than changed logic. It can also affect emitted strictness, because alwaysStrict is part of the bundle, and any pipeline that treats type errors as fatal will now stop. The flag is a bundle of smaller checks, and those can be switched on one at a time instead.

Do shared types make an API safe?

No. A shared type keeps your own code consistent with itself at compile time, which is worth having. It cannot check what a server actually sent, because types are erased before the response arrives. Validation at the boundary is a separate job, covered in the API contracts guide.

Can you run TypeScript files directly?

Often yes. Node strips types without a flag since 23.6, backported to 22.18 and stable since 24.12, and tsx or Deno run them too. Node executes erasable syntax only, ignores tsconfig.json, and refuses TypeScript under node_modules. Stripping is not checking, so you still need tsc, an editor, or a CI step.

Continue Learning TypeScript

• Start at TypeScript Types if annotations, unions, and narrowing are still unfamiliar. Strict-mode errors are much easier to read once they are.
• Read TypeScript Generics for the function types, type parameters, and utility types that appear throughout React props and API models.
• Return to the TypeScript guide for the language overview and the full learning path.