Setup Node.JS-Typescript Project

In my past project, I have been involved in developing node.js-based Backend application, using ES5 and later on, ES6 scripts. As our backend application grew into larger size, complex and hard to debug & maintain, we also encountered an unexpected behaviour. We have an API which should return a success response with desired outcome response object. But, instead of we get the result object on one of the response’s property, we get error message in the property. We concluded that our code has violated the response contract’s specification.

Based on this outcome, we then decided to rewrite the Backend app and selected Typescript as the new language, than using ES6 again. We decided using Typescript, because we want to enforce strong typed contracts across fields, method’s arguments & return type, so that we could eliminate the possibility of such that erroneous behaviour in the rewritten version. The outcome was we often faced build error when we tried passed in argument which has any type or mismatched type. We were happy, because it has improved the quality of our code and the error that we had when we used ES6, did not happen anymore.

Moving fast forwarded to today, I’d like to repeat our of success story by using Typescript language over ES6 when working on any node.js backend apps or libraries first, as I can. In this article, I’d like to share the steps of how to create a Typescript node.js project, in the next following sections.

Pre-requisites

• Ensure that you have installed node.js in your machine. Visit this link to download the installer for Windows/Mac machine. For Linux machine, follow steps described in this link.
• Install typescript through running this command: npm i -g typescript@latest
• Install tslint through running this command: npm i -g tslint@latest

Creating a new Node.js Project

• Create a new folder and initialise the created folder as a Node.js project, through running npm init command in the created folder.

• Add a new .gitignore file and ensure the /node_modules/ folder should be ignored by git client later.

Setup the Node.js project into a Typescript project

• Run tsc --init command to initialise the current directory as a Typescript project. Running the command will create tsconfig.json file.

• Run tslint --init command to initialise Typescript linting setting in current directory. Running the command will create tslint.json file.

• If you wish to let tslint passes any console.log line(s) within your code later, you need to open & edit the tslint.json to be as in the following code snippet:

{
   "defaultSeverity": "error",
   "extends": [
      "tslint:recommended"
   ],
   "jsRules": {
   },
   "rules": {
      "no-console": [false]
   },
   "rulesDirectory": []
}

• Run npm install ts-node tslint typescript typescript-eslint-parser @types/node rimraf --save-dev command for installing required minimum dependencies inside the project directory. After running this command, your package.json file should have devDependencies section which has name of the libraries that we have installed earlier
• Create a new folder in the project’s root directory, and name the new folder as src .
• Open & edit the tsconfig.json with entries shown in the following code snippet

{
   "compilerOptions": {
      "target": "es6",
      "module": "commonjs",
      "outDir": "dist",
      "sourceMap": false,
      "declaration": true,
      "lib": [
        "es2017.object",
        "es2015",
        "es2017"
      ]
   },
   "files": [
      "./node_modules/@types/node/index.d.ts"
   ],
   "include": [
      "src/**/*.ts"
   ],
   "exclude": [
      "node_modules"
   ]
}

• Open & edit the package.json file, and add these npm scripts, which will be used for building the project & cleaning up the build artefacts.

{
...
  "scripts": {
     "build": "tsc && npm run lint",
     "clean": "rimraf ./dist",
     "lint": "tslint -c tslint.json 'src/**/*.ts'",
     "tsc": "tsc",
     "test": "mocha -r ts-node/register src/**/*.spec.ts"
  },
...
}

Testing the setup

At this point, we shall have converted our node.js project as a Typescript project. As for the 1st testing step, we are going to add a new typescript file (let the file is named as app.ts) inside the src subdirectory. Then, we will edit the file with simple code and then run the build npm script. The expected outcome of the build process is, it should produce dist subdirectory and within the subdirectory, it should contain the app.ts file and also the transpiled app.js file. Below are the details steps:

• Create a new typescript file inside the src sub-directory and name it as app.ts In the typescript file, you write a simple code such in this following code snippet:

main();
function main() {
   console.log(`Hello Typescript!`);
}

• Build the project by running npm run build . Confirm that there is no error build appears and a new app.js file is created inside src subdirectory.

• Run node dist/app.js command to test whether the transpiled code is running well or not.

What’s next

In the future, we may want to create more Typescript node.js projects by following this guide. Creating several projects by following the guidance steps in manual way, might take time and prone to human errors. Therefore, we will explore approaches to generate the Typescript node.js project using project scaffolding/generator tool such as Yeoman in the future.