Setting up a TypeScript project from scratch

Enough theory — let us get TypeScript running on your machine, both so you can do every exercise in this course and so you understand the build step that turns .ts into something a computer runs. Expect fifteen minutes and one or two small snags; the lesson anticipates the common ones.

What you need

Two things:

Node.js — the JavaScript runtime. TypeScript compiles to JavaScript, and Node runs it. Install the current LTS from nodejs.org if you do not have it. Check with node --version (any recent version is fine).
An editor with TypeScript support — Visual Studio Code is the standard and its TypeScript support is superb (Microsoft makes both), so this course assumes it. The red underlines and instant error messages you will rely on come from the editor talking to the TypeScript language server.

You do not need to install TypeScript globally; you install it per project, so each project pins its own version — which is exactly what a real team does.

A project from scratch

In a new folder:

npm init -y                          # create package.json
npm install -D typescript            # install the TypeScript compiler, as a dev dependency
npx tsc --init                       # create a tsconfig.json (the project's settings)

Three commands, and you have a TypeScript project:

npm init -y creates package.json, the project's manifest.
npm install -D typescript installs the compiler. -D means "dev dependency" — TypeScript is a build-time tool, not something your shipped app needs at runtime, so it belongs in devDependencies.
npx tsc --init creates tsconfig.json, which tells the compiler how to behave. npx runs the locally-installed tsc (the TypeScript compiler); tsc is the command you will use to compile and type-check. The real-projects module dissects tsconfig.json option by option; for now, the generated default is fine.

Your first typed program

Create hello.ts:

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

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

Now the two-step reality of TypeScript. Compile it to JavaScript:

npx tsc hello.ts        # produces hello.js next to it

and run the JavaScript with Node:

node hello.js           # Namaste, Kavita

That is TypeScript in its raw form: tsc turns hello.ts into hello.js (stripping the types, as the last lesson showed), and node runs the .js. Open hello.js and confirm the : string annotations are gone — the running program is plain JavaScript.

Running TypeScript directly with `tsx`

Compiling then running is two steps, which is tedious for quick work. tsx runs a .ts file directly — compiling in memory and executing in one go:

npm install -D tsx
npx tsx hello.ts        # Namaste, Kavita  — no separate .js file

tsx is what you will use during development for a script or a server, because the edit-run loop is instant. Note one thing, though: tsx runs your code but does not type-check it — it strips the types and runs, fast, without stopping for type errors. So you use both: tsx to run, and tsc --noEmit to type-check.

Type-checking without compiling

Often you do not want any output files — you just want to know "does this type-check?". That is tsc --noEmit:

npx tsc --noEmit        # check every file in the project, produce no .js, just report type errors

This is the command your editor runs constantly under the hood, and the one your CI should run to fail the build on type errors. The workflow that emerges:

tsx file.ts — run it now (no type check).
tsc --noEmit — type-check the whole project (no output).
tsc — compile to .js for shipping (production build).

Add these as package.json scripts so you do not memorise flags:

{
  "scripts": {
    "dev": "tsx src/index.ts",
    "typecheck": "tsc --noEmit",
    "build": "tsc"
  }
}

Now npm run typecheck checks types and npm run dev runs your code — the two commands you will use constantly.

The editor is where you actually work

All of the above matters for understanding and for CI, but day to day you will barely run these commands, because VS Code type-checks as you type. Open a .ts file, make a type error, and a red underline appears instantly with the message — no compile step, no waiting. The editor runs the same TypeScript checker in the background against your whole project. This instant feedback is the real experience of TypeScript, and it is why the setup is worth doing even for small experiments: you see mistakes the moment you make them.

Common snags, pre-empted

tsc: command not found. You tried to run tsc directly instead of npx tsc. Use npx (which finds the locally-installed compiler) or add the script above and use npm run.
"Cannot find name 'console'" or DOM errors. Your tsconfig.json's lib does not include the right environment. The generated default usually works; the tsconfig lesson explains lib.
The editor shows errors the command line does not (or vice versa). They can use different TypeScript versions. In VS Code, set it to use the workspace's TypeScript version (Command Palette → "Select TypeScript Version" → "Use Workspace Version") so the editor and CI agree.
.js files appearing everywhere. tsc emitted them. Use tsx for running and tsc --noEmit for checking during development; only tsc (a real build) should produce .js.

Check your work

The two things you need. Node.js (to run the compiled JS) and an editor with TypeScript support (VS Code).

Why install TypeScript per project, not globally. So each project pins its own compiler version, as a real team does; and -D because it is a build-time tool.

The three setup commands. npm init -y, npm install -D typescript, npx tsc --init.

The raw two-step. tsc file.ts compiles to .js; node file.js runs it — and the emitted JS has no types.

What tsx does, and its catch. Runs a .ts file directly, but does not type-check — so pair it with tsc --noEmit.

What tsc --noEmit is for. Type-check the whole project with no output — what your editor and CI run.

The three-command workflow. tsx to run, tsc --noEmit to check, tsc to build for shipping.

Where you actually work. The editor, which type-checks as you type with instant red underlines.

Practice

Create a project with the three setup commands. Confirm package.json and tsconfig.json exist.
Write hello.ts, compile with tsc, and run the .js with node. Open the .js and confirm the types are gone.
Install tsx and run hello.ts directly. Note there is no .js file.
Introduce a type error. Run it with tsx (it still runs!) and then tsc --noEmit (it reports the error). Explain why they differ.
Add the dev, typecheck, and build scripts to package.json and use npm run typecheck.
In VS Code, make a type error and watch the red underline appear before you run anything.
Set VS Code to use the workspace TypeScript version, and note why the editor and CI should agree.

Official documentation

TypeScript — Download / Get Started — Installing the compiler.
TypeScript — tsc, the compiler — tsc, --noEmit, and the options (dissected later).
tsx — Running TypeScript directly during development.
VS Code — TypeScript — Editor support and selecting the workspace version.

Next module — The Basic Types: everything you will use in your first week.