How to Seamlessly Migrate a Node.js Project to TypeScript: Step‑by‑Step Guide

Introduction

If you have a Node.js project and want to refactor it with TypeScript, this guide will help you. It skips the basics of why TypeScript is popular and focuses on practical steps: directory layout, TypeScript‑ESLint configuration, tsconfig settings, debugging, and common error handling.

Step 1 – Adjust Directory Structure

Because TypeScript needs compilation, separate a src folder for source files and a dist folder for compiled output. A typical layout is:

|-- assets            # images, videos, etc.
|-- bin               # CLI entry, e.g., #!/usr/bin/env node
|-- dist              # compiled files (main points to package.json)
|-- docs              # documentation
|-- scripts           # script files referenced in package.json
|-- src               # only .ts files; other assets go to templates
|-- sub               # sub‑directories
|   └── ...
|-- cli.ts            # CLI entry file
|-- index.ts          # API entry file
|-- templates         # json, html, etc.
|-- tests             # test files
|-- typings           # custom .d.ts files for missing declarations
|-- .eslintignore
|-- .eslintrc.js
|-- .gitignore
|-- package.json
|-- README.md
|-- tsconfig.json

Step 2 – Install and Initialise TypeScript

Run the following commands in the project root:

npm i typescript -D          # install as a dev dependency
node ./node_modules/.bin/tsc --init   # generate tsconfig.json
# or, if TypeScript is installed globally:
# tsc --init

The generated tsconfig.json can be customised; a recommended baseline is provided later.

Step 3 – Adjust Source Files

Rename .js to .ts

Rename all JavaScript files to .ts and move them into src. Tools like gulp can automate this.

Extract Template Files

Files that are not compiled by TypeScript (e.g., .json, .html) should be placed in the templates directory.

Update package.json scripts

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch"
  }
}

Now npm run build or npm run watch compiles the project.

Step 4 – TypeScript Code Standards

Install ESLint for TypeScript:

npm i eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin -D

Create .eslintrc.js with a minimal configuration:

module.exports = {
  parser: '@typescript-eslint/parser',
  extends: ['plugin:@typescript-eslint/recommended'],
  env: { node: true }
};

Optionally extend the standard rule set:

npm i eslint-config-standard eslint-plugin-import eslint-plugin-node eslint-plugin-promise eslint-plugin-standard -D

module.exports = {
  parser: '@typescript-eslint/parser',
  extends: ['standard', 'plugin:@typescript-eslint/recommended'],
  env: { node: true }
};

Integrate ESLint into VSCode for on‑save fixing and real‑time hints.

Step 5 – Resolve Common Errors

Missing Node.js declarations

Install @types/node:

npm i @types/node -D

Import syntax issues

Depending on the module system, use one of the following import styles (with esModuleInterop enabled):

import * as mod from 'mod'

import { foo } from 'mod'

import mod from 'mod'

(default export) import mod = require('mod') (for export = modules)

When esModuleInterop is false, prefer import * as path from 'path' instead of default imports.

No declaration files for third‑party packages

Run npm i @types/packagename -D. If none exist, create a simple declaration in typings/packagename.d.ts:

declare module 'packagename';

Class property initialization

Declare class fields before using them, e.g.:

class Person {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
}

For quick migration, you can temporarily use any but should replace it with proper interfaces later.

Implicit any and unused parameters

Explicitly type function parameters or rename unused ones to _ or prefix with an underscore.

‘this’ typing problems

Declare this as the first parameter in functions that use it:

export default function(this: any, one: string) {
  this.name = 'haha';
}

Step 6 – Debugging Configuration

Debug compiled dist files with a VSCode launch.json like:

{
  "configurations": [{
    "type": "node",
    "request": "launch",
    "name": "debug",
    "program": "/path/to/project/dist/cli.js",
    "args": ["xx"]
  }]
}

Or debug TypeScript directly using ts-node:

{
  "configurations": [{
    "type": "node",
    "request": "launch",
    "name": "debug",
    "runtimeArgs": ["-r", "ts-node/register"],
    "args": ["${workspaceFolder}/src/cli.ts", "xx"]
  }]
}

Step 7 – Strengthen Types and Eliminate any

Gradually replace any with proper interfaces or type aliases. While it’s unrealistic to remove every any in a JavaScript‑origin project, reducing them improves type safety and IDE assistance.

Conclusion

The guide demonstrates a practical workflow for converting a Node.js project to TypeScript, covering directory layout, tooling, common pitfalls, debugging, and incremental type improvement. Although the scope is limited to typical Node.js scenarios, the steps should be adaptable to many projects.

References

[1]

standard: https://standardjs.com/readme-zhcn.html [2] ts-node: https://github.com/TypeStrong/ts-node#visual-studio-code