Install TypeScript with npm and Check Your Version

TypeScript is an npm package called typescript. Install it into your project and check that it works:

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

The package provides the tsc command, the TypeScript compiler. You need Node.js and npm (which ships with Node.js) to install it; get Node.js from nodejs.org or your system's package manager, and check it with node --version.

You do not need anything installed to try TypeScript. This block compiles and runs in your browser:

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

Install TypeScript in a Project

The recommended install is local, as a dev dependency of the project:

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

npm install --save-dev typescript (short form npm i -D typescript) puts the compiler in node_modules and records it in package.json:

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

It is a dev dependency because it is only needed to build the code, not to run it. Anyone who clones the project and runs npm install gets the same compiler version.

To run the local compiler, prefix it with npx, which finds commands in node_modules/.bin:

npx tsc --version

Inside package.json scripts you can write tsc without npx, because npm adds node_modules/.bin to the PATH for scripts:

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

Then npm run build compiles and npm run typecheck checks types without writing any files.

Check the TypeScript Version

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

If npx tsc --version and tsc --version print different versions, the project has its own compiler and the global one is older or newer. The project's version is the one that matters for its build.

Install TypeScript Globally

A global install gives you a tsc command in every terminal, without npx:

npm install -g typescript
tsc --version

On macOS and Linux this can fail with EACCES permission errors when Node.js was installed system-wide. Installing Node.js through a version manager such as nvm or fnm avoids that, and sudo npm install -g is not recommended.

Use the global command for quick experiments. For a real project, keep a local install as well: package.json then records the version, and a global compiler update cannot change how the project builds.

Install with pnpm, Yarn or Bun

Every JavaScript package manager installs the same package:

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

Run the compiler with pnpm tsc, yarn tsc or bunx tsc.

Create a tsconfig.json with tsc --init

A tsconfig.json file marks a folder as a TypeScript project and holds the compiler options. Generate one:

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

The generated file (TypeScript 7) turns on strict and a few more checks, uses "module": "nodenext" and "target": "esnext", and has commented lines for rootDir and outDir. Uncomment those two so the compiler reads from src and writes to dist:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

That is a shortened view; the real file has more options, each with a comment. The tsconfig page explains what they do. Running npx tsc --init again in the same folder fails with error TS5054: A 'tsconfig.json' file is already defined, so it never overwrites your settings.

Compile Your First File

Create src/index.ts:

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

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

Then compile and run:

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

npx tsc with no arguments reads tsconfig.json, type-checks every file it includes, and writes the output to dist. With the generated settings you get index.js plus index.d.ts (type declarations) and .map files (source maps) for each.

Two things to know about the output:

• Type errors do not stop the output by default. tsc reports the errors, exits with a non-zero code, and still writes the JavaScript. Set "noEmitOnError": true to write nothing while there are errors.
• With a tsconfig.json present, do not pass file names. npx tsc src/index.ts fails with error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Run plain npx tsc, or add --ignoreConfig if you really want to compile one file with default settings.

Watch Mode

--watch (short -w) keeps the compiler running and recompiles whenever a file changes:

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

Leave it open in a terminal next to your editor. Stop it with Ctrl+C.

Install a Specific TypeScript Version

Add the version after @:

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6 is the last version whose compiler is written in JavaScript. Some tools that call the compiler's JavaScript API still need it, which the TypeScript 7 page covers along with how to upgrade.

Editor Setup

VS Code has TypeScript support built in: open a .ts file and you get error underlines, autocompletion, hover types and rename without installing anything. For TypeScript 7 speed in the editor, the TypeScript team publishes a dedicated extension that switches VS Code to the native TypeScript 7 language server. WebStorm and the other JetBrains IDEs support TypeScript out of the box, and Neovim, Vim, Emacs, Zed and Sublime Text use a TypeScript language server through their LSP support.

Common Install Errors

This is not the tsc command you are looking for. You ran npx tsc in a folder without TypeScript installed, and npx fetched a deprecated package that happens to be named tsc. Install the real one with npm install --save-dev typescript.

tsc: command not found, or 'tsc' is not recognized as an internal or external command on Windows. TypeScript is not installed globally, or the global npm folder is not on your PATH. Use npx tsc in a project with a local install, or install globally and open a new terminal.

error TS2591: Cannot find name 'process' (or require; __dirname gives TS2304). Node.js's own APIs have their types in a separate package. Install it with npm install --save-dev @types/node, then add "types": ["node"] to compilerOptions: TypeScript 7 no longer loads every installed @types package automatically.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Your files are in src and you set outDir but not rootDir. Add "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y writes "type": "commonjs" into package.json, so the tsc --init config ("module": "nodenext" with verbatimModuleSyntax) treats every .ts file as CommonJS, where import and export are not allowed. Change it to "type": "module", and write relative imports with a .js extension: import { add } from "./math.js".