Leveraging tsconfig.json in TypeScript Projects



Before you start boycotting this blog for boring configuration file posts, I promise you that this is the last one, haha.

The more and more you work with TypeScript, you'll need to become very intimate with tsconfig.json and the different configuration parameters it currently supports.


What is tsconfig.json for?

TypeScript projects! tsconfig.json allows you to configure how your TypeScript project is transpiled. You can specify individual files to be transpiled, exclude certain folders, remove comments, etc. This configuration file is essential in all TypeScript projects, don't forget to include it!


code configuration numbers


When are the configuration settings read?

That occurs when you invoke the TypeScript compiler via "tsc" either through a gulp task, command line or through Visual Studio TypeScript settings.

Note that tsconfig.json is only gained support with TypeScript 1.5+, previous versions will not read the configuration settings!


Where do you store tsconfig.json?

Typically you will have only one tsconfig.json in your project, but you can have numerous versions that you can localize to different folders.

First thing first, if you specify the "files" you want to transpile, the settings found inside of that tsconfig.json will apply only to those files. If you do NOT specify the files explicitly, then the compiler will pick up the current directly and move up the parent chain.


tsconfig.json in Detail

You probably scrolled down to this section as soon as you opened the post because you either had no idea what I was talking about or wanted an example to go off of. Apologies, but there is some logic to my madness :)


Example of a basic tsconfig.json file


{
    "compilerOptions": {
        "module": "amd",
        "noImplicitAny": true,
        "removeComments": false,
        "preserveConstEnums": true,
        "outFile": "../../build/fullProject.js",
        "sourceMap": false
    },
    "files": [
        "core.ts",
        "sys.ts",
        "types.ts",
    ]
}


"compiler options"

The meat and potatoes of what you're going to configure here. We will go through each one so you have a firm grasp of what they're used for. Note that there are options added throughout the current development and this list may not include everything that is on the bleeding edge.


"module"

//Stuff above
 "compilerOptions": {
        "module": "amd",
//Stuff below

Here is where you pick which module you want the TypeScript compiler to transpile your wonderful .ts files to. There are four options:

  • commonjs
  • amd
  • system
  • umd

We won't go into too much detail on what each one is and how the code differs but I would HIGHLY recommend checking out this link:

Writing Modular JavaScript

"noImplicitAny"

//Stuff above
    "compilerOptions": {
        "noImplicitAny": true,
//Stuff below

Do you like warnings? This one is pretty good, it lets you know if any of your expressions or declarations have an implied "any" type. The "any" type in TypeScript is basically telling TypeScript that you are too lazy to define the type or you don't care. If you're going to take the time to write TypeScript, set this to true and follow it like the bible.


"removeComments"

//Stuff above
    "compilerOptions": {
        "removeComments": false,
//Stuff below

Can you guess what this one is? Haha this will remove all the comments in your TypeScript code when its transpiled to JavaScript. I usually turn this to true because I want my .js files to not carry any bloat. That said, I rarely comment my code and I am pretty religious about writing clean code. Clean code != comments.


"preserveConstEnums"

//Stuff above
    "compilerOptions": {
        "preserveConstEnums": true,
//Stuff below

Tells the compiler not to erase const enum declarations in your generated code. This can be useful for debugging, leave this to true.


"outFile"

//Stuff above
        "compilerOptions": {
            "outFile": "../../build/fullProject.js",
//Stuff below

With HTTP 2.0, I would highly recommend against setting an outFile. What this option does is concatenates all of your transpiled .ts files and outputs a single file into a location. AVOID THIS


angry asian lady lol

"outDir"

//Stuff above
        "compilerOptions": {
            "outDir": "../../build/",
//Stuff below

I use "outDir" if I don't have this wired up to my Gulp task. What "outDir" does is redirect all of your transpiled files(along with the folder structure) to the specified directory.


"sourceMap"

//Stuff above
"compilerOptions": {
        "sourceMap": false
//Stuff below

There is always some ongoing debate about map files... I tend to only use this in development while debugging. This flag, if set to true, will transpile .js along with the associated '.map' files.


"target"

//Stuff above
"compilerOptions": {
        "target": ES5
//Stuff below

The default for this puppy is "ES5", but there are three options:

  • ES3
  • ES5
  • ES6

And who said that ES6 and TypeScript can't play nice together? Typically I leave this at the default of "ES5" since that is what is supported by most browsers. Note that as ES6 gains traction with TypeScript all you have to do is change one line of code in the future!


"target"

//Stuff above
"compilerOptions": {
        "target": ES5
//Stuff below

The default for this puppy is "ES5", but there are three options:

  • ES3
  • ES5
  • ES6

And who said that ES6 and TypeScript can't play nice together? Typically I leave this at the default of "ES5" since that is what is supported by most browsers, this is ever changing as ES6 gains traction, but with TypeScript all you have to do is change one line of code in the future!


are we there yet penguins

The finish line

The meat of tsconfig.json was in the compiler options...but we aren't done yet! There are two other parameters that you can specify to be specific in what files are transpiled and which ones arent.

"files"

//Stuff above
    "files": [
        "core.ts",
        "sys.ts",
        "types.ts",
],
//Stuff below

Remember, if this parameter is omitted, the compiler will transpile ALL of the .ts files in the containing directory. When you want control, you use "files".

SIDE NOTE: I know the gents at the TypeScript team are working hard to provide glob support but at this time it's a little bit of a disaster to use the "files" property. If you wanted to do something neat like "*.controller.ts", you can't, because there isn't any glob support. There is an active open issue that is still being debated: Globs Support in tsconfig.json

Why is "files" a disaster you ask? Because do you really want to specify every single .ts file manually and maintain them all here in this tsconfig.json file? I sure don't...


"exclude"

//Stuff above
    "exclude": [
        "node_modules",
        "wwwroot"
    ]
//Stuff below

The "exclude" property is basically the opposite of "files" except you specify the folders you want to exclude. Typically you don't want to have a "files" property living alongside "exclude" because it turns into a cluster real fast. "files" takes precedence over the "exclude" property if you decide to include both.

I suspect we'll get the bang "!" operator pretty soon and eliminate "exclude" altogether.


Atom TypeScript

If you're using the Atom editor you have a really great option at your disposal, a spin-off from the traditional tsconfig.json that gives you "!" and glob support. Check out the following package:

Atom-TypeScript
atom typescript gif


atom editor

Until next time!

[Date Edited: 7/8/2016 6:22:06 AM ]

Leave a Comment