Wednesday, July 25, 2018

Learn Typescript compiler option,tsconfig.json file

typescript configuration file

Every typescript project has tsconfig.json file root directory. tsconfig is abbreviated as typescript configuration file. This file contains all the configuration parameters for typescript compiler.Angular 2+ is based on the typescript. Every Angular project has this file in the project root directory. Browsers will not understand the typescript file, so There is a process called compile/transpile to compile typescript code and generates javascript code

All the configuration parameters you specified in this file will be considered during the compilation phase. Once typescript is installed(Already posted an article about how to install typescript language) globally or locally, tsc command is available.

Typescript file can be generated using tsc command or Angular cli tool.

Using tsc command line

tsc --init
this outputs configuration file in the root directory with basic configuration options as defined below Here is sample tsconfig.json file

{
  "compilerOptions": {
    /* Basic Options */
    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    // "lib": [],                             /* Specify library files to be included in the compilation. */
    // "allowJs": true,                       /* Allow javascript files to be compiled. */
    // "checkJs": true,                       /* Report errors in .js files. */
    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
    // "declaration": true,                   /* Generates corresponding '.d.ts' file. */
    // "sourceMap": true,                     /* Generates corresponding '.map' file. */
    // "outFile": "./",                       /* Concatenate and emit output to single file. */
    // "outDir": "./",                        /* Redirect output structure to the directory. */
    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
    // "removeComments": true,                /* Do not emit comments to output. */
    // "noEmit": true,                        /* Do not emit outputs. */
    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */

    /* Strict Type-Checking Options */
    "strict": true,                           /* Enable all strict type-checking options. */
    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
    // "strictNullChecks": true,              /* Enable strict null checks. */
    // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
    // "strictPropertyInitialization": true,  /* Enable strict checking of property initialization in classes. */
    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */

    /* Additional Checks */
    // "noUnusedLocals": true,                /* Report errors on unused locals. */
    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */

    /* Module Resolution Options */
    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
    // "typeRoots": [],                       /* List of folders to include type definitions from. */
    // "types": [],                           /* Type declaration files to be included in compilation. */
    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
    "esModuleInterop": true                   /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */

    /* Source Map Options */
    // "sourceRoot": "./",                    /* Specify the location where debugger should locate TypeScript files instead of source locations. */
    // "mapRoot": "./",                       /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */

    /* Experimental Options */
    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
  }
}

Using Angular cli

Angular CLI is a tool used to generate a new Angular application from scratch. You don't need to write any file to set up a project. with just one command, Your application prototype source code is available This tool also generates a typescript configuration file in the project root directory.

Typescript compiler options

We will go through different compiler options available with detailed explanation target option:-
Typescript compiles into javascript. There are different versions of javascript - ES5, ES6, and ES7. This option provides compatible generated files specific to the corresponding target version of javascript possible values are ES3 - Default, ES5, ES6(ES2015), ES2016, ES2017, ESNEXT.

Module Option: 
This option is to generate code using modules. Modules are of different types like CommonJS, None, System, UMD, AMD, ES6. default options are CommonJS if target specified as ES3 or ES5, else ES6 is default module.

experimentalDecorators option

ES2017 has proposed experimental decorators which are not yet accepted. if we are using those decorators in typescript sourcecode, It will throw an error. This option enables decorators for typescript. decorators are supported from ES2017 release onwards. By setting this option, errors will be ignored. By default it is false.

emitDecoratorMetadata  option

This option is needed for decorators metadata. By default it is false. Metadata is a feature in ES2017 specs and to tell about runtime information of class, method or function. metadata are typescript reflection API which provides information about decorators.
This option will preserve type information in your object's metadata.

compileOnSave option

This option is a not related typescript and works with IDE like visual studio, web storm and atom.if any changes in Typescript files, It automatically saves and compiles to javascript code.


baseUrls/path option
This option to allow typescript to pick type files from this location.

alwaysStrict option
This option allows enabling type-safe checking. The compiler compiles all typescript files with strict mode. emits warnings if any. In each file, It includes 'use Strict' in each javascript generated file.

sourceMap option
By default it is false. if true, generates source maps for debugging purpose

AllowJS Option 
This option allows javascript source code to be compiled as part of transpile process. The default is false.

strictNullChecks option
when strictNullChecks=false, the below code works as null and undefined types can be assigned to number types.
let numberVariable: number = 45;
numberVariable = null; // no issues
numberVariable = undefined; // no issues
when strictNullChecks=true, the below code does not works
let numberVariable = undefined;
numberVariable = null; // As undefined and null are different

outDir option
This option allows compiler generate output files in this directory.

removeComments option
The default is false. remove comments from generated source files.


Include and Exclude options
This Include option will allow adding this files for compilation of source code. In the same way, we can specify files to excluded from a compilation of code

{
    "include": [
        "src/main/webapp/app",
        "src/main/webapp/app/app.main.ts",
        "src/test/javascript/"
    ],
    exclude": [
        "node_modules",
    ]
}