Adding TypeScript Support to an Existing Node.js Project (Without Dropping JavaScript Support)

Why I Made This Update

Managing errors in JavaScript can be tricky, especially in large projects where type-related issues may not surface until runtime. To improve type safety and catch errors at compile time, I decided to introduce TypeScript into my existing Node.js backend project. However, I didn’t want to completely drop JavaScript support, so I configured my environment to support both JavaScript and TypeScript files.

How to Add TypeScript to an Existing Node.js Project

To allow both JavaScript and TypeScript files to coexist in a Node.js project, follow these steps:

Step 1: Install Required Dependencies

Run the following command in your project’s root directory:

npm install --save-dev @types/node ts-node typescript

These packages help enable TypeScript support and provide type definitions for Node.js.

Step 2: Create a tsconfig.json File

This configuration file tells TypeScript how to compile your code. Below is a generic configuration that works for most projects:

{
    "compilerOptions": {
        "target": "es2016",
        "module": "commonjs",
        "allowJs": true,      // Allow JavaScript files
        "checkJs": true,      // Enable type checking for JS files
        "outDir": "./dist",  // Compiled files will be placed here
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "strict": true,       // Set to false initially for easier migration
        "skipLibCheck": true,
        "moduleResolution": "node",
        "resolveJsonModule": true,
        "baseUrl": ".",
        "paths": {
            "*": ["node_modules/*"]
        }
    },
    "include": ["*.ts"],
    "exclude": ["node_modules", "dist"]
}

Step 3: Enable TypeScript Execution Without a Build Step

Instead of compiling TypeScript into JavaScript before running the backend, I use ts-node to execute TypeScript files directly. To achieve this, I added the following in my main JavaScript entry file:

require('ts-node').register({
  transpileOnly: false,
  compilerOptions: {
    module: 'commonjs',
    allowJs: true,      // Allow JavaScript files
    checkJs: false,     // Disable type-checking for JavaScript files
    esModuleInterop: true
  }
});

This allows me to mix JavaScript and TypeScript files in my backend without requiring a separate build process.

Managing Imports Between JavaScript and TypeScript

Importing JavaScript Files in TypeScript:

import { rabbitMqClient } from "./filepath";

Importing TypeScript Files in JavaScript:

const fileName = require("./filepath");

Since JavaScript doesn’t support TypeScript syntax, require() must be used instead of import when loading TypeScript files from a JavaScript file.

Pros and Cons of Supporting Both JavaScript and TypeScript

Pros:

• Gradual migration: You don’t have to rewrite the entire codebase in TypeScript.
• Type safety: TypeScript catches errors at compile-time, reducing runtime bugs.
• Improved code maintainability: Better tooling support and autocompletion.

Cons:

• TypeScript errors are not raised if starting from a JavaScript entry file: Since TypeScript checks don’t apply in pure JavaScript files, errors may go unnoticed if you start from a .js entry point and navigate into .ts files.
• Inconsistent typing enforcement: When managing services between .ts files, type safety works fine. However, when jumping between .js and .ts files, there may be type inconsistencies.
• Potentially confusing imports: Developers need to be mindful of import/export differences between JavaScript and TypeScript.

Final Thoughts

This setup allows my backend to gradually transition to TypeScript while maintaining JavaScript support. However, this method is only for backend code. For frontend migration, additional steps are required, which I will cover in a separate blog post.

Let me know if you have any questions or suggestions! 🚀