Installing TypeScript and your first compile

Beginner · 4 min

Install TypeScript per project, compile a file with tsc, read the emitted JavaScript, and use --init, --watch, and --noEmit.

Before thisWhy TypeScript, and what a type checker does

Net Ninja · 4 min

Installing TypeScript and your first compile

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by Net NinjaReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • Install TypeScript as a dev dependency of each project with `npm install --save-dev typescript`, so every developer and the CI server use the same compiler version, and run it with `npx tsc`.
  • The `tsc` compiler does two separate jobs: it type-checks your code and it emits JavaScript. By default it still emits JavaScript even when the type check fails, and signals the failure through its exit code.
  • `npx tsc --init` writes a `tsconfig.json`. Once that file exists, running plain `npx tsc` compiles the whole project using its settings, while `npx tsc file.ts` does not use it (current versions refuse with an error rather than silently ignoring the config).
  • `tsc --watch` keeps the compiler running and rechecks only what changed on each save, which is much faster than a cold run.
  • `--noEmit` turns `tsc` into a pure type checker, the usual setup when a bundler or runtime handles turning TypeScript into JavaScript.

One compiler version per project

TypeScript ships as an npm package called typescript, and the package contains the compiler, a command called tsc. You need Node.js installed to run it (setting up Node is covered in the nodejs roadmap).

You could install it globally, but the better habit is per project:

mkdir hello-ts && cd hello-ts
npm init -y
npm install --save-dev typescript
npx tsc --version

The reason is the same reason you pin any dependency. Each TypeScript release adds checks and tightens existing ones, so two versions can disagree about whether the same code has errors. With a local install, the version is recorded in package.json and the lockfile, and every developer and the CI server run the identical compiler. npx tsc finds the copy in node_modules/.bin.

Your first compile

Create src/greet.ts:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("Ada"));

Then compile it:

npx tsc src/greet.ts
node src/greet.js

A new src/greet.js appears next to the source. Open it and the type annotations are gone. This is type erasure from the previous lesson, now on your own disk. Depending on your compiler version’s defaults, the template literal may also have been rewritten into older string concatenation, because tsc can also downlevel modern syntax for older runtimes. Which syntax gets rewritten is controlled by the target option, covered in the next lesson.

Checking and emitting are separate jobs

Now break the call:

console.log(greet(42));
npx tsc src/greet.ts
# src/greet.ts:5:19 - error TS2345: Argument of type 'number'
#   is not assignable to parameter of type 'string'.

Here is the part most people do not expect: greet.js was still written. tsc does two independent things, type checking and emitting JavaScript, and by default an error in the first does not stop the second. A type error is a warning about your logic, not a syntax error that makes the code impossible to produce.

What changes is the exit code. tsc exits with a non-zero status when it finds errors, so a CI step or an npm script that runs it will fail. If you want no output at all when the check fails, set the noEmitOnError option.

The opposite setup is common too. Many projects never use tsc to produce JavaScript. A bundler such as Vite, a framework build, or a runtime that strips types does that part, and tsc only checks:

npx tsc --noEmit

--noEmit runs the full type check and writes nothing. In a typical modern project this is the command in the typecheck script your CI runs.

A project file with --init

Compiling files one by one does not scale. tsc --init creates a tsconfig.json in the current folder:

npx tsc --init

The generated file sets a handful of options, with many more listed in comments, and recent versions of TypeScript produce a shorter, more opinionated starting point than older ones did. Once it exists, run tsc with no file names:

npx tsc

The compiler now finds every file the config includes and applies its options. One trap: if you pass a file name, as in npx tsc src/greet.ts, tsc doesn’t use tsconfig.json at all. Older versions silently fell back to defaults, a classic source of “my settings don’t work” confusion. TypeScript 6.0 refuses instead, with error TS5112 telling you the config won’t be loaded, and --ignoreConfig if you really mean it. What the individual options mean is the subject of tsconfig explained.

Watch mode

A full compile on every save gets slow. Watch mode keeps the compiler alive:

npx tsc --watch
# or combined with a pure check:
npx tsc --watch --noEmit

tsc does one full pass, then waits. When you save a file it rechecks only what the change can affect and prints the new error list, usually in a fraction of the original time, because the compiler keeps its earlier work in memory. Leave it running in a terminal beside your editor and the error count updates as you type.

A typical package.json ends up with scripts like these:

{
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "dev": "tsc --watch"
  }
}

What the video covers

Net Ninja’s clip is short and does the core loop well: install the typescript package, run tsc on a .ts file, and look at the JavaScript it produces. It only touches watch mode lightly and doesn’t cover tsc --init, the fact that tsc emits even when it finds errors, or --noEmit. Those are the parts of this lesson to read carefully, since they decide how tsc behaves in a real project and in CI. If you want a longer CLI walkthrough, Harry Wolff’s video in the links below spends more time on --init and watch mode, though its generated config reflects an older TypeScript version.

Check yourself

  1. 01Why install TypeScript locally in each project instead of globally?

    A local install pins the compiler version in `package.json` and the lockfile, so every machine and the CI server check the code with exactly the same rules. A global install varies from developer to developer and can report different errors for the same code.

  2. 02You run `npx tsc` on a file with a type error. Do you get a `.js` file?

    Yes, by default. Type checking and emitting are independent, so `tsc` reports the error, exits with a non-zero code, and still writes the JavaScript. Setting `noEmitOnError` makes it skip emitting when there are errors.

  3. 03What does `tsc --noEmit` do, and when would you use it?

    It runs the full type check but writes no output files. You use it when something else, such as a bundler, a framework build, or a runtime that strips types, produces the JavaScript, and you only want `tsc` to verify the types, for example in CI.

  4. 04You created a `tsconfig.json`, then ran `npx tsc src/index.ts`, and your settings were ignored. Why?

    Passing file names on the command line tells `tsc` to compile just those files with default options, so it does not read `tsconfig.json`. Older versions silently ignored the config; TypeScript 6.0 stops with error TS5112 instead, unless you add `--ignoreConfig`. Running `npx tsc` with no file arguments, or `npx tsc -p tsconfig.json`, uses the project file.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark