Compiler options

Introduction

Compiler options are contained within a tsconfig.json file and specify how TypeScript should compile our code.

Initializing a file

We can initialize a tsconfig.js file in a project by running tsc --init. This will create a file with all off the different options, however majority of them will be commented out.

Basic example

We are going to look at a very basic example containing only a few of the compiler options:

	{
	  "compilerOptions": {
	    "target": "es2016",
	    "sourceMap": true,
	    "outDir": "scripts",
	    "strict": true,
	    "watch": true
	  },
	  "files": ["src/index.ts"]
	}

Let’s look at the different properties we set in our compiler options.

• target: This is the version of ECMASCript that will be used for our compiler. TypeScript Docs link
• sourceMap: This links the JavaScript back to our TypeScript file which is helpful for debugging purposes. You will see that a .map file is additionally generated. TS Docs link.
• outDir: This specifies where our built files should be generated. In our example we set this to scripts which means our JavaScript files will be generated in a /scripts directory. TS Docs link.
• strict: This turns on a variety of different TypeScript “rules” which will ultimately allow in better type checking and a better application. TS Docs link
• watch: This enables a watch mode so that our files are watched for changes and automatically recomplied if any changes are detected. TS Docs link

Source maps:

Source maps link your TypeScript and JavaScript files. They allow you to debug more effectively. In the Sources tab of your browser, you can set breakpoints in your TypeScript file which will then pause your code while it’s running the JavaScript.

Running tsc

We can run the tsc command with a file name which will then compile the file we’ve specified.

If we have a tsconfig.json file then we will not need to specify a file. TypeScript will instead use the paths specified in tsconfig.json. Additionally, you can tsc in any sub-directory and TypeScript will attempt to find the tsconfig.json file and continue up the parent directory chain until it finds it.

If you wanted to run everything manually, you have the following options:

• tsc src/*.ts: This will compile all of the Typescript files in the src folder.
• tsc --project tsconfig.production.json: This will compile files based on a specific tsconfig.json file. This lets you have different configurations for different environments.
• tsc src/*.ts --target es2016 --outfile index.js: This will target a version we’ve specified and output to a index.js file.

Specifying file names and include/exclude

We can specify a list of file names that we want TypeScript to compile.

For example, the following tsconfig.json will compile the following files:

• src/index.ts
• src/example-1.ts
• src/example-2.ts

	{
	  "compilerOptions": {
	    "target": "es2016",
	    "sourceMap": true,
	    "outDir": "scripts",
	    "strict": true,
	    "watch": true
	  },
	  "files": ["src/index.ts", "src/example-1.ts", "src/example-2.ts"]
	}

Specifying exact files is not very helpful as we’d need to keep this updated with new files we have created.

We can instead use include to specify a list of files we want to compile, and exclude to exclude directories of files to exclude.

In the example below we are going to compile all of our TypeScript files, however we will be ignoring our node_modules folder as well as any test files.

	{
	  "compilerOptions": {
	    "target": "es2016",
	    "sourceMap": true,
	    "outDir": "scripts",
	    "strict": true,
	    "watch": true
	  },
	  "include": ["src/**/*"],
	  "exclude": ["node_modules", "**/*.spec.ts"]
	}

Configuration inheritance

We can have multiple tsconfig.json files per project.

We are going to add another config file and use that config.

Before we start, let’s have a look at our initial setup.

	/* Greets a person */
	function greetPerson(name: string): string {
	  return `Hello, ${name}`;
	}
	
	greetPerson('Ola');

We have a TypeScript file that contains a function with a comment on top of the function, /* Greets a person */. We will remove this comment with our 2nd configuration to show that it’s working.

Above: A /* Greets a Person */ comment showing in our JavaScript output file.

In this example, we have our initial tsconfig.json file in the root directory of our project: /tsconfig.json.

We then create a new tsconfig.json file in src. We use the extends property to tell TypeScript which config file this one is extending from. We also additionally specify that comments must be removed.

/src/tsconfig.json:

	{
	  "extends": "../tsconfig",
	  "compilerOptions": {
	    "removeComments": true,
	  }
	}

To run this config file, we will run tsc in the src folder so that it finds the closest tsconfig.json file.

You can see that our terminal has output that the files are being watched, which indicates that our initial base tsconfig.json was being used as the watch command was only specified here.

Furthermore, we can see that the comment has been removed from our index.js file, indicating that our extended tsconfig.json file is also working.

Above: The comment no longer showing indicating that our tsconfig.json was extended correctly.

Lesson task

Goal

To demonstrate a basic understanding of the tsconfig.json file as well as be aware of the different options available.

Brief

Follow the Level 1 Process as instructed.

NOTE: Lesson tasks do not get submitted on Moodle and are not assessed by tutors. They are mainly there for you to practise what you have learned in the lesson.

Level 1 process

1. Briefly read through the following page to see the different options available to you when it comes to the compiler options: https://www.typescriptlang.org/tsconfig.
2. Create a new tsconfig.json file in a project.
3. Make sure that all of the files are included, however make sure tha node_modules and your test files are excluded.
4. Add any options you might be interested in to see how it make impact your project.
5. Create a different tsconfig.json file and extend this from your initial tsconfig.json file.

Additional resources

TypeScript docs: What is a config.json

TypeScript docs: TSConfig Compiler options