4 How does TypeScript work? The bird’s eye view

This chapter gives the bird’s eye view of how TypeScript works: What is the structure of a typical TypeScript project? What is compiled and how? How can we use IDEs to write TypeScript?

4.1 The structure of TypeScript projects

This is one possible file structure for TypeScript projects:

typescript-project/
  dist/
  ts/
    src/
      main.ts
      util.ts
    test/
      util_test.ts
  tsconfig.json

Explanations:

• Directory ts/ contains the TypeScript files:
  • Subdirectory ts/src/ contains the actual code.
  • Subdirectory ts/test/ contains tests for the code.
• Directory dist/ is where the output of the compiler is stored.
• The TypeScript compiler compiles TypeScript files in ts/ to JavaScript files in dist/. For example:
  • ts/src/main.ts is compiled to dist/src/main.js (and possibly other files)
• tsconfig.json is used to configure the TypeScript compiler.

4.1.1 tsconfig.json

The contents of tsconfig.json look as follows:

{
  "compilerOptions": {
    "rootDir": "ts",
    "outDir": "dist",
    "module": "commonjs",
    ···
  }
}

We have specified that:

• The root directory of the TypeScript code is ts/.
• The directory where the TypeScript compiler saves its output is dist/.
• The module format of the output files is CommonJS.

4.2 Programming TypeScript via an integrated development environment (IDE)

Two popular IDEs for JavaScript are:

• Visual Studio Code (free)
• WebStorm (for purchase)

The observations in this section are about Visual Studio Code, but may apply to other IDEs, too.

One important fact to be aware of is that Visual Studio Code processes TypeScript source code in two independent ways:

• Checking open files for errors: This is done via a so-called language server. Language servers exist independently of particular editors and provide Visual Studio Code with language-related services: detecting errors, refactorings, auto-completions, etc. Communication with servers happens via a protocol that is based on JSON-RPC (RPC stands for remote procedure calls). The independence provided by that protocol means that servers can be written in almost any programming language.
  • Important fact to remember: The language server only lists errors for currently open files and doesn’t compile TypeScript, it only analyzes it statically.
• Building (compiling TypeScript files to JavaScript files): Here, we have two choices.
  • We can run a build tool via an external command line. For example, the TypeScript compiler tsc has a --watch mode that watches input files and compiles them to output files whenever they change. As a consequence, whenever we save a TypeScript file in the IDE, we immediately get the corresponding output file(s).
  • We can run tsc from within Visual Studio Code. In order to do so, it must be installed either inside project that we are currently working on or globally (via the Node.js package manager npm).
  With building, we get a complete list of errors. For more information on compiling TypeScript from within Visual Studio Code, see the official documentation for that IDE.

4.3 Other files produced by the TypeScript compiler

Given a TypeScript file main.ts, the TypeScript compiler can produce several kinds of artifacts. The most common ones are:

• JavaScript file: main.js
• Declaration file: main.d.ts (contains type information; think .ts file minus the JavaScript code)
• Source map file: main.js.map

TypeScript is often not delivered via .ts files, but via .js files and .d.ts files:

• The JavaScript code contains the actual functionality and can be consumed via plain JavaScript.
• The declaration files help programming editors with auto-completion and similar services. This information enables plain JavaScript to be consumed via TypeScript. However, we even profit from it if we work with plain JavaScript because it gives us better auto-completion and more.

A source map specifies for each part of the output code in main.js, which part of the input code in main.ts produced it. Among other things, this information enables runtime environments to execute JavaScript code, while showing the line numbers of the TypeScript code in error messages.

4.3.1 In order to use npm packages from TypeScript, we need type information

The npm registry is a huge repository of JavaScript code. If we want to use a JavaScript package from TypeScript, we need type information for it:

• The package itself may include .d.ts files or even the complete TypeScript code.
• If it doesn’t, we may still be able to use it: DefinitelyTyped is a repository of declaration files that people have written for plain JavaScript packages.

The declaration files of DefinitelyTyped reside in the @types namespace. Therefore, if we need a declaration file for a package such as lodash, we have to install the package @types/lodash.

4.4 Using the TypeScript compiler for plain JavaScript files

The TypeScript compiler can also process plain JavaScript files:

• With the option --allowJs, the TypeScript compiler copies JavaScript files in the input directory over to the output directory. Benefit: When migrating from JavaScript to TypeScript, we can start with a mix of JavaScript and TypeScript files and slowly convert more JavaScript files to TypeScript.

• With the option --checkJs, the compiler additionally type-checks JavaScript files (--allowJs must be on for this option to work). It does so as well as it can, given the limited information that is available. Which files are checked can be configured via comments inside them:

  • Explicit excluding: If a JavaScript file contains the comment // @ts-nocheck, it will not be type-checked.
  • Explicit including: Without --checkJs, the comment // @ts-check can be used to type-check individual JavaScript files.

• The TypeScript compiler uses static type information that is specified via JSDoc comments (see below for an example). If we are thorough, we can fully statically type plain JavaScript files and even derive declaration files from them.

• With the option --noEmit, the compiler does not produce any output, it only type-checks files.

This is an example of a JSDoc comment that provides static type information for a function add():

/**
 * @param {number} x - The first operand
 * @param {number} y - The second operand
 * @returns {number} The sum of both operands
 */
function add(x, y) {
  return x + y;
}

More information: Type-Checking JavaScript Files in the TypeScript Handbook.