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:

• JavaScript + jQuery + Webpack, no frameworks.
• 5+ years of enterprise.
• 1M+ unique users a month.
• Growing with new features.

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:

• Increase in codebase complexity.
• Difficulty in understanding the project.
• Decline in relevancy of the app from a tech point of view.
• Lack of interest among developers working with the same old technologies.

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:

• Handle increasing codebase complexity by implementing strict rules and following them.
• Make the codebase more understandable with TypeScript’s self-documenting capabilities.
• Keep the project in line with modern technologies.
• Maintain motivation within the development team to learn and develop.

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:

• Save time ( == money) on possible bug fixing.
• Decrease the risks of costly bugs appearing in production.
• Slow down the growing backlog.
• Decrease the cost of onboarding new developers to the project with the help of improved documentation.
• Increase developer productivity.

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:

• We used TypeScript for newly created files
  

• Since the project is still being developed, components are getting redesigned and constantly refactored, so we areexpected to create new files.

• We converted existing JS to TS when possible
  

  Whenever we had the rare opportunity to take a pause from developing features, we dedicated it to technical improvements like rewriting entire files to TS.

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

• JavaScript to TypeScript ratio in the project
  

  Let's compare the number of lines of code for both JS and TS inside the project:

  JS: 9190 total(76.5%)

  TS: 2812 total(23.5%)

  Not bad so far!

• Decreased backlog
  

  For the first time in many years, we managed to resolve most of our backlog, which, of course, is a result of different parameters, but TypeScript still contributed to this achievement.
  

• The Dev team acquired new skills
  

  This process was also quite fun for some of our developers who weren't very familiar with TypeScript. It kept them entertained and motivated to reach for new heights in their professional lives!

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.