Setting Up TypeScript: The Compiler, tsconfig, and Your Toolchain

So you’ve decided to give TypeScript a try. Good call. But the very first time most people sit down to actually use it, they hit a wall of unfamiliar words: compiler, tsc, tsconfig.json, build step, watch mode. None of it is hard once you see how the pieces fit together, but nobody is born knowing it.

This article walks you through that setup, slowly and from the ground up. We won’t tie ourselves to any particular editor, framework, or build tool. Instead, the goal is for you to understand what each part actually does, so that no matter what project you join later, the setup makes sense instead of feeling like magic.

Why TypeScript needs a setup step at all

Plain JavaScript runs directly. You hand a .js file to a browser or to a runtime like Node.js, and it runs. There’s no in-between.

TypeScript is different, and the reason is simple: browsers and runtimes don’t understand TypeScript. They only understand JavaScript. TypeScript is a layer you write on top of JavaScript that adds types — little labels that describe what kind of value something is (a number, a piece of text, a list of users, and so on). Those type labels are wonderful while you’re writing code, because they catch mistakes early. But they mean nothing to the machine that eventually runs the program.

So there has to be a step that takes your TypeScript and turns it into ordinary JavaScript. That step is called compiling (you’ll also hear “transpiling” — for our purposes treat them as the same thing). The tool that does it is the TypeScript compiler.

Meet the compiler: tsc

The TypeScript compiler is a program called tsc (short for TypeScript compiler). Its job is to read your .ts files, check them for type errors, and write out matching .js files.

You install it through npm, the package manager that comes with Node.js. Most of the time you install it inside your project rather than globally on your whole computer, so that every project can pin its own version:

npm install --save-dev typescript

The --save-dev part means “this is a development tool, not something my app needs while running.” Once it’s installed, you can run the compiler:

npx tsc --version

npx is a small helper that runs a tool installed in your project. If it prints a version number, the compiler is ready.

Now imagine you have a tiny file called app.ts:

function greet(user: { name: string }): string {
  return "Hello, " + user.name;
}

const jane = { name: "Jane Doe" };
console.log(greet(jane));

Compile it:

npx tsc app.ts

The compiler reads app.ts, checks the types (here it confirms that greet is given an object with a name that is text), and produces app.js sitting right next to it. That app.js is plain JavaScript with the type labels stripped away — that’s the file you can actually run.

What compiling actually removes

It helps to see the before and after. The TypeScript above becomes roughly this JavaScript:

function greet(user) {
  return "Hello, " + user.name;
}

const jane = { name: "Jane Doe" };
console.log(greet(jane));

Notice what disappeared: the : { name: string } and the : string. Those were the types. They guided the compiler while it checked your work, and then they were erased, because the running program doesn’t need them. This is a key mental model — types exist at compile time, not at run time. They’re a safety net during development that gets folded away before the code ships.

The role of tsconfig.json

Running tsc app.ts by hand is fine for a single file. Real projects have dozens or hundreds of files, plus a pile of preferences: which JavaScript version to target, where to put the output, how strict to be about mistakes. Typing all of that on the command line every time would be miserable.

That’s what tsconfig.json is for. It’s a single configuration file that lives at the root of your project and tells the compiler how to behave. When you run tsc with no file name, the compiler looks for tsconfig.json, reads your preferences from it, and compiles the whole project accordingly.

You can generate a starter one:

npx tsc --init

A minimal, readable tsconfig.json might look like this:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["src"]
}

Let’s read it the way the compiler does:

The big idea: instead of describing the build every single time, you describe it once in tsconfig.json, and from then on a bare tsc command does the right thing.

Separating source from output

Notice how the config above keeps rootDir (src) and outDir (dist) apart. This is a habit worth forming. Your hand-written TypeScript lives in src. The compiler’s generated JavaScript lands in dist. You never edit files in dist by hand — they’re rebuilt from src every time you compile.

A typical layout looks like this:

my-project/
├─ src/
│  └─ app.ts        ← you write this
├─ dist/
│  └─ app.js        ← tsc generates this
├─ tsconfig.json    ← compiler settings
└─ package.json     ← project + dependencies

Keeping the two folders separate means your real work stays clean, and you can safely delete dist whenever you want — it’ll come right back on the next build. (It’s also common to tell version control to ignore dist entirely, since it can always be regenerated.)

Watch mode: compile as you type

Re-running tsc after every change gets old fast. The compiler has a built-in answer called watch mode. You start it once, and it keeps running, recompiling automatically the moment you save a file:

npx tsc --watch

Now the loop becomes: edit a file, save, and the compiler instantly rebuilds and re-checks everything. If you introduce a type error, it shows up in your terminal right away instead of waiting until you remember to compile. For day-to-day development this is the mode you’ll usually leave running in a corner of your screen.

Where TypeScript fits in a modern toolchain

Here’s where many beginners get confused, so let’s clear it up. In a small project, tsc does two jobs at once: it type-checks your code, and it produces the JavaScript output. Simple and self-contained.

But in larger or front-end projects, you’ll often see a different arrangement. A separate build tool (a bundler) handles turning your many files into the final assets the browser loads, and it does the TypeScript-to-JavaScript conversion as part of that process — usually by simply stripping the types out, very fast, without doing the type-checking.

That sounds contradictory until you separate the two responsibilities:

   What TypeScript gives you
   ┌─────────────────────────────┐
   │ 1. Type checking            │ ← catches mistakes (correctness)
   │ 2. Stripping types → JS     │ ← produces runnable code
   └─────────────────────────────┘

A modern toolchain frequently splits these:

• The build tool / bundler takes care of step 2 quickly, so your app runs.
• A separate tsc --noEmit run takes care of step 1, checking types without writing any output files (--noEmit means “check, but don’t produce JavaScript”).

That’s why you’ll sometimes see a project where tsc is configured not to emit files at all. It’s not broken — the build tool is doing the emitting, and tsc has been narrowed down to the one thing it’s best at: being the source of truth for type correctness.

You don’t need to memorize every variation. The thing to carry with you is the split: “make the code run” and “make sure the types are correct” are two separate jobs, and different tools can own them.

A clean starting point, start to finish

Putting it all together, a from-scratch setup for a small project is just a handful of steps:

# 1. Start a project
npm init -y

# 2. Add the TypeScript compiler as a dev tool
npm install --save-dev typescript

# 3. Create a tsconfig.json
npx tsc --init

# 4. Write code in src/, then compile
npx tsc

# 5. Or develop with auto-recompile
npx tsc --watch

From here you’d typically add a script to package.json so you can run npm run build instead of remembering the raw command — but that’s polish. The mental model underneath stays exactly the same.

Recap

TypeScript adds a small but real setup step, and now you know why and what each piece is doing:

• TypeScript is for writing; JavaScript is for running. The compiler bridges them.
• tsc is that compiler. You install it per-project with npm and run it with npx tsc.
• Compiling checks your types and emits plain JavaScript, with the type labels removed. Types live at compile time, not run time.
• tsconfig.json is the project’s settings file. Describe your build once there, and a bare tsc does the rest. Start with strict: true and keep source (src) separate from output (dist).
• Watch mode (tsc --watch) recompiles automatically as you save, tightening the feedback loop.
• In a modern toolchain, type-checking and code-generation are often split between tsc and a build tool. Knowing that they’re two jobs is what keeps real-world setups from looking like magic.

Get comfortable with this and the rest of your TypeScript journey rests on solid ground. Everything else — fancier configs, frameworks, bigger tooling — is just variations on the same handful of ideas you just learned.