TypeScript Tutorial

TypeScript Compiler

Browsers and Node.js cannot run TypeScript directly. A compiler turns your TypeScript code into plain JavaScript first.

Note: Because TypeScript is converted into JavaScript, it runs anywhere JavaScript runs.

Installing the Compiler

TypeScript has an official compiler. You install it with npm, the package manager that comes with Node.js.

Note: If npm is new to you, read a short introduction to npm first.

Inside your npm project, run this command to install the compiler:

npm install typescript --save-dev

You should see output similar to:

added 1 package, and audited 2 packages in 2s
found 0 vulnerabilities

The compiler is installed in the node_modules directory. You can run it with npx tsc.

That command should print something like:

Version 4.5.5
tsc: The TypeScript Compiler - Version 4.5.5

This is followed by a list of all the common commands.

Installing Globally

Installing TypeScript globally adds the tsc command to your system PATH, so you can use it from any folder.

npm install -g typescript
tsc -v

Pros

Quick access to tsc from any project or directory.
Useful for trying commands, learning, or one-off scripts.
Some editors or tools can find a global compiler automatically.

Cons

Different machines (or teammates) may have different global versions.
The global version can drift from the version your project expects, which causes subtle issues.
On some systems you need elevated permissions to install globally.

Note: The best practice is to install TypeScript as a project devDependency and run it with npx tsc. That way the exact version is the same in every environment. A global install is optional and handy for quick, ad-hoc use.

Configuring the compiler

By default the TypeScript compiler prints a help message when you run it in an empty project.

You configure the compiler with a tsconfig.json file.

TypeScript can create a tsconfig.json with recommended settings for you:

npx tsc --init

You should see output similar to:

Created a new tsconfig.json with:
target: es2016
module: commonjs
strict: true
esModuleInterop: true
skipLibCheck: true
forceConsistentCasingInFileNames: true

You can learn more in the TypeScript Config chapter.

Here is an example of more settings you could add to tsconfig.json:

"include": ["src"]
"compilerOptions": { "outDir": "./build" }

Open the file in an editor to add those options.

With these settings the compiler takes the TypeScript files in the src/ directory of your project and writes JavaScript files into the build/ directory.

Your First TypeScript Program

Let's write a simple "Hello, World!" program to check that your TypeScript setup works.

Create a new file named hello.ts with the content shown in the first snippet below.
Compile your TypeScript code with npx tsc hello.ts. This creates a hello.js file in the same directory (see the second snippet).
Run the compiled JavaScript with node hello.js.

You should see the output Hello, World!.

Note: If you use the tsconfig.json configuration from above, put your TypeScript files in the src directory. The compiled JavaScript then appears in the build directory.

hello.ts

A typed greet function that builds a greeting string, and a message variable that is printed with console.log.

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

const message: string = greet("World");
console.log(message);

Compiled hello.js

The JavaScript that the compiler generates from hello.ts — the type annotations are gone and the template string became a concat call.

function greet(name) {
  return "Hello, ".concat(name, "!");
}

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