This tutorial shows how to build a TypeScript project with the help of tsconfig.json.
The file tsconfig.json is TypeScript specific and its presence in a directory indicates that the directory is the root of a TypeScript project.
The content of this file specifies the root files and the compiler options required to compile the project.

Example

In this example we are not going to use any IDE to show that tsconfig.json and the compiler alone can be used to build a TypeScript project

Creating a project folder

Let's create a project folder:

D:>mkdir typescript-project-example

Creating tsconfig.json

we can use tsc --init to create a default tsconfig.json file:

D:\typescript-project-example>tsc --init
message TS6071: Successfully created a tsconfig.json file.

D:\typescript-project-example>type tsconfig.json
{
  "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. */
    // "declarationMap": true,                /* Generates a sourcemap for each 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. */
    // "composite": true,                     /* Enable project compilation */
    // "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. */
    // "strictBindCallApply": true,           /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
    // "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. */
  }
}

As seen above there're many options which can be used. In this tutorial we will use some basic options only, so let's open above file in notepad++ and modify to:

tsconfig.json

{
  "compilerOptions": {
    "target": "es6", /*Specify ECMAScript target version*/
    "rootDir": "ts-src",/*ts source direcotry*/
    "outDir": "web-app/js" /*where to compile javascript files*/
  }
}

Where the value of 'rootDir' is the folder which will contain our TypeScript source code and 'outDir' is the folder where compiler will emit the compiled javascript files.

Adding TypeScript source files

Let's create 'ts-src' folder and add an example ts file:

ts-src/hello.ts

function getMessage(): string {
    return "hi there";
}

Now we have following directory structure

D:\typescript-project-example>tree /a /f
Folder PATH listing for volume Data
Volume serial number is 68F9-EDFA
D:.
|   tsconfig.json
|   
\---ts-src
        hello.ts
        

Invoking tsc in watch mode

When tsc is invoked without any input files, the compiler searches for the tsconfig.json file starting in the current directory and continuing up the parent directory chain.

In our example we are going to invoke tsc in the project root directory without any input ts files. So the compiler will pick up configuration from our tsconfig.json.
We are also going to use --watch option which causes the compiler to watch the source files and auto compile upon changes (we could have also added watch=true in our tsconfig.json file).

This will cause the compiler to go in watch mode:

[23:53:58 PM] Starting compilation in watch mode...

[23:53:59 PM] Found 0 errors. Watching for file changes.

That also created our 'web-app/js' folder with js compiled file.

D:\typescript-project-example>tree /a /f
Folder PATH listing for volume Data
Volume serial number is 68F9-EDFA
D:.
|   tsconfig.json
|   
+---ts-src
|       hello.ts
|       
\---web-app
    \---js
            hello.js
            

If we change our source code and save, or add new ts files the changes will be reflected in our outDir.

Adding other web files

Let's add an HTML source file in our 'web-app' folder:

web-app/index.html

<html>
<head>
    <script type="text/javascript" src="./js/hello.js"></script>
</head>
<body>
<div id="display-div"></div>
<script>
    document.getElementById("display-div").innerHTML = getMessage();
</script>
</body>
</html>

Now we have following project structure:

D:\typescript-project-example>tree /f /a
Folder PATH listing for volume Data
Volume serial number is 68F9-EDFA
D:.
|   tsconfig.json
|   
+---ts-src
|       hello.ts
|       
\---web-app
    |   index.html
    |   
    \---js
            hello.js
            

Running

We will use Node http-server to run our web application. Open a new cmd and run following in our web-app folder:

D:\typescript-project-example\web-app>http-server -c-1
Starting up http-server, serving ./
Available on:
  http://192.168.0.2:8080
  http://127.0.0.1:8080
Hit CTRL-C to stop the server

In above command the -c option specifies the cache time in seconds, e.g. -c10 for 10 seconds. To disable caching we used -1 i.e. -c-1.

Let's access our index.html page, in web browser:

Let's modify our ts file and save:

ts-src/hello.ts

function getMessage(): string {
    return "<h2>hi there .....</h2>";
}

Refresh the web page:

In the next tutorial we will see how to auto refresh web pages when we save ts files.

Example Project

Dependencies and Technologies Used:

• TypeScript 3.2.2
• Node.js v10.14.1