Installing TypeScript and Project Setup

Introduction

TypeScript ships as an npm package. After you have Node.js and npm, installing the compiler takes one command. This chapter covers global versus project-local installation, verifying tsc, and generating your first tsconfig.json so the compiler knows how to check and emit your code.

Prerequisites

• Node.js LTS and npm installed and working (node --version, npm --version)
• If Node is not set up yet, use the JavaScript track install chapters for your OS
• A terminal (PowerShell, Terminal, or bash) and a folder where you can create a practice project

What You Are Installing

The main package is typescript. It provides:

• tsc — the TypeScript compiler (type-check and emit JavaScript)
• tsserver — language service used by editors (VS Code uses it automatically)

You do not install a separate “TypeScript runtime.” Compiled output still runs on Node.js or in the browser as JavaScript.

Global Install vs Project-Local Install

Global installation

npm install -g typescript

Verify:

tsc --version

Code explanation:

• -g installs the tsc command globally so you can run it from any directory
• Version output confirms the compiler is on your PATH

Project-local installation (recommended)

Create a folder and initialize npm:

mkdir ts-hello
cd ts-hello
npm init -y

Install TypeScript as a development dependency:

npm install --save-dev typescript

Run the local compiler via npx:

npx tsc --version

Code explanation:

• --save-dev records typescript under devDependencies—needed for build/check, not for production runtime
• npx runs the project’s installed tsc without relying on a global install

Your package.json will look similar to:

{
  "name": "ts-hello",
  "version": "1.0.0",
  "devDependencies": {
    "typescript": "^5.8.0"
  }
}

Exact version numbers change over time; the caret (^) allows compatible minor updates when you run npm update.

Add a Compile Script (Optional but Useful)

In package.json:

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

Code explanation:

• build runs the compiler using settings from tsconfig.json
• typecheck checks types without writing .js files (--noEmit)—handy in CI

Then run:

npm run build

Generate tsconfig.json

The compiler reads tsconfig.json in your project root (or a file you pass with -p). It defines:

• which .ts files to include
• target JavaScript version (target)
• module system (module)
• output folder (outDir)
• strictness and other compiler options

Create a starter config:

npx tsc --init

This writes a tsconfig.json with many commented options. For learning, you can start with a smaller explicit file:

Code explanation:

• target: JavaScript language level emitted by tsc
• module / moduleResolution: how import/export are resolved (Node-style in this example)
• outDir / rootDir: compiled .js goes to dist/, source stays in src/
• strict: enables the strict type-checking family (recommended for new projects)
• include: which source files belong to this project

A matching layout:

ts-hello/
├── package.json
├── tsconfig.json
└── src/
    └── (your .ts files here)

You will explore each option in depth in a later chapter. For now, treat tsconfig.json as the project settings file for TypeScript.

Quick Sanity Check

Create src/hello.ts:

const message: string = "TypeScript is installed";
console.log(message);

Compile:

npx tsc

Run the output:

node dist/hello.js

Expected: one line printed to the terminal. If compile fails, read the error text—TypeScript errors are usually file paths, tsconfig options, or type mistakes.

Global vs Local: Which tsc Am I Running?

Check:

which tsc
tsc --version
npx tsc --version

On Windows PowerShell:

Get-Command tsc
tsc --version
npx tsc --version

If versions differ, trust npx tsc inside the project directory for that repo.

Common Setup Problems

Install Checklist

• node --version and npm --version succeed
• typescript listed in devDependencies (for project work)
• npx tsc --version prints a 5.x (or current) version
• tsconfig.json exists at project root
• npx tsc compiles a sample .ts file without errors
• node runs the emitted .js file

FAQ

Do I need to install TypeScript globally?

No. Project-local install with npx tsc is the standard for applications and libraries.

Is TypeScript the same as installing @types/node?

No. The typescript package is the compiler. @types/node (installed separately) provides type definitions for Node.js APIs—you add it when writing server-side TypeScript.

Can I use TypeScript without tsconfig.json?

You can compile single files with npx tsc src/hello.ts, but real projects almost always use tsconfig.json for consistent options and file lists.

What does strict: true do?

It turns on a group of stricter checks (such as strictNullChecks and noImplicitAny). New projects should keep it enabled unless you have a deliberate migration plan.

Should I commit tsconfig.json to git?

Yes. It is part of your project contract—same as package.json and lockfiles.