One day, you wake up and decide you can't live without TypeScript in your legacy JavaScript project anymore. That's what happened to me and my сolleagues, too, and now I want to tell you about our experience.

About the project:

Step 1. Understanding the needs

The longer you develop an app, the more complex it becomes. With time, we realized that we couldn't ignore the following issues anymore:

Why TypeScript? Besides the obvious benefits, such as handy static typing, a self-documented codebase, and enhanced code reliability, we found a few nice advantages for our project specifically:

TypeScript could help us:

Step 2. Convincing the management team

These benefits were enough to convince the development team to adopt TS, but we still had to convince the management team of the reason to spend money on implementing TypeScript. The points above didn't seem convincing enough to explain what management would get from this transition. Well, we had some arguments here, too.

TypeScript could help the management team:

As a result, we managed to get approval and started the task!

Step 3. Adding TypeScript to the project

First, we needed to install TypeScript as a dev dependency:

npm install typescript

Also, we needed a basictsconfig.json file to make it work inside the project as recommended:

  {
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "strict": true
  }
}

Of course, it wasn't that easy, right? Let's see what issues we had.

Since we're using Webpack in our project, we had to show it how to approach TS files. To do this, we added a ts-loader package:

npm install --save-dev ts-loader
and added parameters to the Webpack config file:

module.exports = {
  module: {
    rules: [{
        test: /\\.ts$/,
        exclude: /node_modules/,
        use: 'ts-loader'
      }]
  }
}

Also, there was a need to tell our linter to check TS files, too:

module.exports = {
  plugins: [
    new ESLintPlugin({
      extensions: './*.{js,ts}',
      files: './*.{js,ts}'
    })
  ]
}

Since we are using jQuery in our project (jQuery is still alive in 2025!), we needed types for jQuery:

npm install --save-dev @types/jquery

Voila! TypeScript was now working in our project. But what next? Our project still completely consisted of JS. How did we transition it to TS?

Step 4. Transitioning the project to TS

We couldn't afford to convert all the JS files to TS simultaneously, so we decided to do this gradually. We chose the following strategy:

This is still a work in progress, but we have some results after 1 year of the transition:

I collected some thoughts from my teammates on their current experience with TS, especially from those who hadn't used it or other typings in programming before:

  1. It took some time to get familiar with TS, and it felt difficult at the beginning, but eventually, they got used to it and now see the benefits of using TS.
  2. The best thing is that TypeScript highlights the expected type or the wrong ones that were passed. This is really handy and saves time.
  3. TypeScript adds predictability when it comes to the complex logic of components (that's what I meant by "handle increasing codebase complexity"!)
  4. A downside is that it requires a bit more time to write in TS, but it is still worth it.
  5. Sometimes, creating the right type can be challenging (thank goodness we love challenges)
  6. There were an enormous number of cases when errors were prevented before even running the code.
  7. Our code became more readable and self-documented.
  8. People like working with TypeScript because it can be exciting.

If you've read the article to this point, this is your sign to put some TypeScript in your legacy project! It's worth it and not that painful after all.