Getting Started

TypeScript is JavaScript with a static type system layered on top. The compiler, tsc, checks your types and then emits plain JavaScript, which Node.js or a browser runs as usual. Keep one fact in mind from day one: types exist only at compile time. Nothing about them survives into the code that actually runs.

This chapter walks through installing Node.js and TypeScript, configuring a project with tsconfig.json, the common ways to run TypeScript code, and setting up your editor.

Install Node.js

The TypeScript compiler ships as an npm package, so you need Node.js first. Grab the LTS release from nodejs.org, or use a version manager such as nvm if you work across several projects with different requirements. Then confirm the install:

node --version
npm --version

Create a project and add TypeScript

Rather than installing TypeScript globally, add it to each project as a dev dependency. That way everyone on the team, and your CI server, compiles with exactly the same version.

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

npx tsc runs the compiler from the local node_modules. Next, generate a config file:

npx tsc --init

Understanding tsconfig.json

tsc --init writes a heavily commented tsconfig.json. You can trim it down to the options that matter while you are learning:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Turn on strict from the very first commit. Enabling it later on an established codebase tends to surface hundreds of errors at once. Every option is documented in the TSConfig reference.

Your first program

Create src/index.ts:

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

const message = greet("TypeScript");
console.log(message);

The : string parts are type annotations. Call greet(42) and the compiler rejects it before the code ever runs. Because the config uses "module": "nodenext", also add "type": "module" to package.json so Node treats the emitted files as ES modules. Then build and run:

npx tsc
node dist/index.js

tsc checks everything under src and writes dist/index.js. One surprise for newcomers: by default it still emits JavaScript even when there are type errors. If you would rather block output on errors, enable noEmitOnError.

Running TypeScript without a build step

Compiling before every run gets tedious during development. tsx executes .ts files directly by stripping the types on the fly. It does not type-check, though, so pair it with tsc --noEmit, which checks without writing any files.

npm install --save-dev tsx
npx tsx src/index.ts
npx tsx watch src/index.ts
npx tsc --noEmit

Recent Node.js releases can also run .ts files natively by erasing type annotations. Syntax that needs real code generation, such as enum, has limited support there, so check the documentation for the Node.js version you use before relying on it.

Wire the common commands into package.json so nobody has to remember them:

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "start": "node dist/index.js"
  }
}

Editor setup

Visual Studio Code bundles the TypeScript language service, so completions, inline errors, rename, and go-to-definition work out of the box. A few habits make it even better:

• Run TypeScript: Select TypeScript Version from the command palette and pick "Use Workspace Version", so the editor and npx tsc agree.
• Hover over any variable to see its inferred type. This is the first thing to check when the compiler disagrees with you.
• Long error messages read best from the bottom up; the last line usually names the real mismatch.
• Add ESLint and Prettier to catch common mistakes and keep formatting consistent.

JetBrains IDEs such as WebStorm support TypeScript out of the box as well. To experiment without installing anything, open the TypeScript Playground in your browser.

Summary

• TypeScript is type-checked and compiled to JavaScript; types disappear at runtime.
• Install it per project with npm install --save-dev typescript and run it via npx tsc.
• Enable strict in tsconfig.json from the start.
• Use tsc for builds, tsx for quick runs during development, and tsc --noEmit for type checking.