Setting Up TypeScript

The 24-chapter TypeScript for Beginners series keeps its toolchain deliberately small: Node.js, npm and one compiler. This chapter installs TypeScript in a fresh project, generates the tsconfig.json that controls every build, and sets up the compile-and-watch loop you will use for the rest of the series — including a first compiled example with its expected terminal output, and the one adjustment TypeScript needs when it meets Vite.

Installing TypeScript

TypeScript is an ordinary npm package, installed as a development dependency because it never ships to the browser — only the compiled JavaScript does. Create a playground folder and install it:

mkdir ts-playground
cd ts-playground
npm init -y
npm install -D typescript
npx tsc --version

Expected output:

Version 5.9.2

Two habits are worth forming now. The -D flag keeps typescript out of your production dependencies, and npx tsc runs the compiler installed inside this project. A global install feels convenient but quietly makes different projects compile with different versions — one of the nastier sources of “it works on my machine” bugs.

tsconfig.json: the control panel

npx tsc --init writes a tsconfig.json in the current folder. The generated file is long and mostly commented out, documenting every option the compiler understands; real projects edit only a handful of keys:

npx tsc --init

Expected output: no console output — a tsconfig.json file simply appears next to package.json. Trim it to this, which is the configuration this series assumes:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

The compile and watch workflow

With a config in place, a bare npx tsc compiles every file matched by include. A successful build prints nothing at all — silence is success:

mkdir src
# create src/main.ts first
npx tsc

Expected output: no messages, and a fresh dist/ folder containing main.js. Typing that command after every save gets old quickly, so pass --watch (or -w) and let the compiler follow you around:

npx tsc --watch

Expected output:

[09:15:02] Starting compilation in watch mode...
[09:15:02] Found 0 errors. Watching for file changes.

Every save triggers a recompile; errors print into the same window and the process stays alive, so one broken line never ends your session. When you only want the verdict — in a script, a pre-commit hook or continuous integration — use npx tsc --noEmit to type-check without writing any files.

Your first compiled example

Create src/greeting.ts with a tiny typed program:

const price: number = 49.5;
const taxRate: number = 0.2;
const total: number = price * (1 + taxRate);

console.log(`Total: ${total.toFixed(2)}`);

Compile it, then run the emitted JavaScript with Node:

npx tsc
node dist/greeting.js

Expected output:

Total: 59.40

The file landed in dist/ because of outDir, and Node happily ran the result — proof that .js is all a runtime ever needs. Now break the build on purpose by changing only the annotation:

const total: string = price * (1 + taxRate);

Expected output:

error TS2322: Type 'number' is not assignable to type 'string'.

The maths is fine; the promise is not. Restore : number and tsc goes silent again. One detail to know: type errors do not stop JavaScript being written by default, so add "noEmitOnError": true to compilerOptions if you never want broken output reaching dist/.

TypeScript with Vite

Most modern projects do not hand-run tsc — a build tool drives everything. Vite understands TypeScript out of the box, and its starter templates come in plain-JS and TS flavours:

npm create vite@latest ts-vite-app -- --template vanilla-ts
cd ts-vite-app
npm install
npm run dev

Expected output:

VITE v6.x.x  ready in 400 ms

  ➜  Local:   http://localhost:5173/

Three facts make the Vite setup predictable:

• Dev mode is transpile-only — Vite uses esbuild to strip types instantly, without checking them, so red squiggles come from your editor rather than the dev server.
• The build script checks first — the generated build script runs tsc before bundling (typically tsc -b && vite build), which is where type errors surface.
• One config each — tsconfig.json sits beside vite.config.ts; moduleResolution: "bundler" matches how Vite resolves imports. The react-ts template uses the same arrangement if you continue into Setting Up React with Vite.

How this series uses the project

Keep one folder open for all 24 chapters: a src/ source directory, a dist/ build directory, and one file per chapter — src/ch03-annotations.ts, src/ch04-arrays.ts and so on. Leave tsc --watch running in a second terminal pane so every snippet you type is checked the moment you save it. Typing the examples yourself, errors included, is what turns reading into skill.

Common mistakes

• Running a stale global compiler — a bare tsc may resolve to an old global install; use npx tsc so the project's own version runs.
• Compiling one file by name — tsc src/main.ts makes the compiler ignore tsconfig.json entirely, so outDir, include and strict silently stop applying.
• Expecting type errors from npm run dev — Vite's dev server transpiles without checking; rely on your editor, or run the build script.
• Editing files in dist/ — that folder is regenerated on every compile; change the sources in src/ instead.
• Running tsc with an empty include — compiling before any file exists under src/ yields No inputs were found in config file 'tsconfig.json'; create the file first.

Practice checklist

1. Install TypeScript locally and confirm npx tsc --version reports a 5.x release.
2. Generate tsconfig.json with tsc --init, trim it to the six options above, and explain each one aloud.
3. Compile the tax example, run it from dist/, and confirm Total: 59.40.
4. Reintroduce the string annotation, read the TS2322 error, then start tsc --watch and watch errors appear and disappear as you edit.
5. Scaffold the vanilla-ts Vite template and verify that a deliberate type error shows in the editor but not in the running dev server.

What's next?

The compiler is installed, the config is understood and the watch loop is running — now write real annotations in Basic Types and Annotations.