Installing and running the compiler

In this lesson, we will learn how to install and run the TypeScript compiler in a local project.

Technical requirements

You will need the following installed on your computer for this lesson:

• Node.js and npm. You can download these from https:/​/​nodejs.​org/​en/​download. If you already have these installed, make sure that Node.js is at least version 8.2, and that npm is at least version 5.
• Code editor such as Visual Studio Code. This can be installed from https:/​/​code.​visualstudio.​com.

Creating the project

We are going to start this lesson by creating an npm project.

• Open Visual Studio Code (or your chosen editor) in a folder of your choice.

• Create a file called index.ts and paste in the following content:

Copy
function firstOrNull<T>(array: T[]): T | null {
  return array.length === 0 ? null : array[0];
}

• Open the Terminal window and enter the following to initialize the project:

Copy
npm init

• When prompted, enter "program" for the package name. Accept defaults for the other prompts.

A package.json is created containing the values you have just specified.

That completes the project setup.

Running the compiler without installing TypeScript into the project

There is a way to use the TypeScript compiler without installing TypeScript. The npx tool can be used to temporarily install TypeScript and run the compiler.

• In the Terminal window, run the following command:

Copy
npx -p typescript tsc index.ts

Let's break this command down:

• This command first downloads and installs the typescript npm package.
• tsc is the executable name of the TypeScript compiler. So, once typescript has been installed, the TypeScript compiler is invoked.
• index.ts is the TypeScript file that we want to compile.
• After the compilation has finished, the typescript npm package will be uninstalled.

After the command has run, an index.js will exist containing the following transpiled code:

Copy
function firstOrNull(array) {
  return array.length === 0 ? null : array[0];
}

The type annotations have been removed during the transpilation process.

• Delete index.js.

• Change the TypeScript function to reference an invalid property by changing length to count:

Copy
function firstOrNull<T>(array: T[]): T | null {
  return array.count === 0 ? null : array[0];
}

• Rerun the TypeScript compiler:

Copy
npx -p typescript tsc index.ts

A type error is raised in the Terminal window:

Notice that the JavaScript file is still created even though there has been an error.

• Delete index.js.

• There is a compiler option to stop the creation of the JavaScript file if there is an error. This option is called noEmitOnError. Let's try this:

Copy
npx -p typescript tsc index.ts --noEmitOnError

The error is still raised, but the JavaScript file isn't created this time.

• Correct the problem in the function before we move on to the next section:

Copy
function firstOrNull<T>(array: T[]): T | null {
  return array.length === 0 ? null : array[0];
}

Using a local version of TypeScript

TypeScript can be managed as a project dependency like other dependencies. This is the more common approach of using TypeScript in a project.

• Let's install the typescript npm package as a development dependency:

Copy
npm install typescript --save-dev

After this has finished, typescript will appear as a dev dependency in package.json.

• We need to add an npm script in package.json for invoking the TypeScript compiler:

Copy
"scripts": {
  ...
  "tsc": "tsc"
},

• We can now run the tsc command, in the Terminal window:

Copy
npm run tsc index.ts

An index.js file is created.

• Delete index.js before continuing to the next section.

Specifying configuration options

The TypeScript compiler has lots of options. Details of all the available options can be found here.

We can pass compiler options into the tsc command, as we have seen, but there is a more convenient approach. We can define all the options in a file called tsconfig.json.

• Create a tsconfig.json containing the following:

Copy
{
  "compilerOptions": {
    "outDir": "dist"
  }
}

• Run the following command, in the Terminal window:

Copy
npm run tsc

The generated JavaScript file is placed in a dist folder.

Neat!

Summary

npx is a nice lightweight approach to compiling TypeScript code. The more common approach is to install TypeScript into the project as a development dependency.

The TypeScript compiler has lots of options that can be defined in a tsconfig.json file.

In the next lesson, we will learn about the available options for determining what files to compile.