How to Seamlessly Integrate TypeScript into Your Node.js Projects

Translated from Ross Bulat’s “Typescript with NodeJS: An Integration Guide”. Original link: https://medium.com/@rossbulat/typescript-introduction-with-nodejs-c160c4362746

As of December 2018, about 47% of JavaScript developers have adopted TypeScript in their tech stacks. This article shows how to install and correctly configure TypeScript in a Node.js project, helping you decide whether to adopt it.

What Exactly Is TypeScript?

TypeScript 3.x adds types and interfaces to JavaScript and includes features such as iterators, decorators, and namespaces to improve scalability and readability. It is essentially a type system for JavaScript, not a new language.

Migrating existing projects to TypeScript often reveals hidden bugs and makes code more readable. Types improve data structure visibility and overall code quality.

TypeScript’s popularity is evident from over 4 million weekly NPM downloads and more than 3 000 open issues on GitHub, with frequent updates that follow the JavaScript specification.

TypeScript works with frameworks like React and Angular, though this guide focuses on Node.js.

How to Use TypeScript

Typically you install TypeScript globally for development. The tsc command compiles all .ts files under the src/ directory into .js files placed in dist/. Source files remain in src.

IDE Support

Many IDEs support TypeScript. Visual Studio integrates TypeScript tools automatically. Sublime Text 3 can use the TypeScript plugin via Package Control, or you can install it manually:

cd ~/"Library/Application Support/Sublime Text 3/Packages"
git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript

Windows users should follow the plugin’s installation instructions.

Installing TypeScript with Node

If you need a fresh branch for TypeScript work, create one:

git branch origin typescript
git checkout typescript

Or install it globally:

npm install -g typescript

Modifying package.json

Add scripts to compile TypeScript:

# package.json
{
  "scripts": {
    ...
    "build-ts": "tsc",
    "watch-ts": "tsc -w",
    ...
  }
  ...
}

Run yarn build-ts or npm run build-ts to compile, and yarn watch-ts for automatic recompilation.

Adding a tsconfig.json File

Create tsconfig.json in the project root. Example for Node.js:

# tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "esModuleInterop": true,
    "target": "es6",
    "noImplicitAny": true,
    "moduleResolution": "node",
    "sourceMap": true,
    "outDir": "dist",
    "baseUrl": ".",
    "paths": {
      "*": ["node_modules/*", "src/types/*"]
    }
  },
  "include": ["src/**/*"]
}

Key options explained: module: "commonjs" – Node’s module format. esModuleInterop: true – Enables default import syntax. target: "es6" – Emits ES6‑compatible JavaScript. noImplicitAny: true – Disallows implicit any types. moduleResolution: "node" – Uses Node’s module resolution. sourceMap: true – Generates source maps for debugging. outDir: "dist" – Output directory for compiled files.

If you already have a src/ folder, you may create a separate ts-src/ folder and point tsconfig.json to it, but continue referring to it as src/ in this guide.

Adding DefinitelyTyped Files

TypeScript uses .d.ts files to provide type information for JavaScript libraries. Most popular libraries already have these definitions.

Method 1: Install @types Packages

For example, to add types for the mongodb module:

npm i --save @types/mongodb
# or
yarn add @types/mongodb --dev

Method 2: Use dts-gen

If a library lacks a definition, generate one with dts-gen:

#install dts-gen
npm install -g dts-gen

#install some_module
npm install -g some_module

#generate .d.ts file for some_module
dts-gen -m some_module

Method 3: Create a Blank Declaration File

When generation fails, add an empty declaration:

# src/types/some_module.d.ts

declare module "some_module";

Compiling a Simple TypeScript File

Create src/helloworld.ts:

// src/helloworld.ts

const msg: string = "Hello World!";
console.log(msg);

Compile with the script added earlier:

# compile TypeScript

yarn build-ts

The compiled helloworld.js appears in dist/. Use yarn watch-ts for automatic recompilation.

Converting an Express Template to TypeScript

Move all source files to src/ and adjust the entry point. After compilation, replace the original app.js with the generated one in dist/. Update bin/www (or create bin/ts-www) to require the compiled file:

# old dependency
var app = require('../app');

# new dependency
var app = require('../dist/app');

Testing with Jest

Install Jest with TypeScript support: npm install -D jest ts-jest Add jest.config.js:

#jest.config.js
module.exports = {
  globals: {
    'ts-jest': {
      tsConfigFile: 'tsconfig.json'
    }
  },
  moduleFileExtensions: ['ts', 'js'],
  transform: {
    '^.+\\.(ts|tsx)$': './node_modules/ts-jest/preprocessor.js'
  },
  testMatch: ['**/test/**/*.test.(ts|js)'],
  testEnvironment: 'node'
};

Running npm run test will pre‑compile TypeScript tests in memory and execute them.

Next Steps

This article explained how to introduce TypeScript into a Node project, configure the compiler, add .d.ts definitions, and progressively migrate from .js to .ts. For deeper language features, refer to the TypeScript Handbook in the official documentation.