Enabling TypeScript Strict Mode in a Legacy React Project—A Gradual Approach

The Project Background

Our App was created in 2017. It is a React application written in TypeScript. At the time, TypeScript was gaining popularity, but strict type safety wasn’t a major concern for most teams. Our knowledge of TypeScript was limited, and the primary goal was to use it for basic type annotations rather than enforcing a fully type-safe codebase.

As a result, TypeScript’s strict mode was not enabled. This meant that the codebase lacked certain safeguards, such as strict null checks, no implicit any, and more rigorous type inferences. Over time, as the project grew in size and complexity, the lack of strict typing introduced subtle bugs and made refactoring riskier.

Fast forward to today, the project has grown significantly. It now consists of approximately 2270 TypeScript files, making it a massive undertaking to migrate to strict mode. However, the benefits of enabling strict mode—better type safety, easier maintenance, and fewer runtime errors—outweighed the challenges. This blog post documents our journey of making this transition, the challenges we faced, and the strategies we used to make it manageable. 

The Challenge of Enabling Strict Mode

Simply turning on strict mode in the tsconfig.json file immediately resulted in over 6,000 TypeScript errors across the codebase. This was expected but still overwhelming. The idea of fixing every single error before moving forward was impractical for several reasons:

• Addressing all these issues at once would have meant halting new feature development and improvements for weeks, if not months. Given the scale of the project, such a pause was not an option.
• Many parts of the application had been running without issues for years. Fixing these areas would provide little immediate value and could even introduce unnecessary risk.
• Forcing the entire team to stop their current work and focus solely on type fixes would have been demotivating and inefficient.
• A full migration to strict mode needed a gradual, non-disruptive approach—one that allowed the team to continue delivering value while incrementally improving type safety. The next step was finding a way to introduce strict mode without breaking everything at once.

A Gradual Transition Approach

With strict mode enabled, we needed a way to manage the transition without disrupting ongoing development. Instead of attempting to fix all 6,000+ errors at once, we took a pragmatic approach by suppressing errors in a controlled way while allowing for incremental fixes over time.

To achieve this, we developed a Python script that automated the process:

• The script runs tsc with strict mode enabled and captures all compilation errors in a log file.
• It processes the error output to determine which files and lines contain type issues.
• It automatically opens each file with errors and adds TODO: @ts-expect-error comments at the appropriate locations.

By doing this, the entire project immediately compiles successfully again, even with strict mode enabled. This allowed us to:

• Continue feature development without being blocked by TypeScript errors.
• Incrementally clean up @ts-expect-error comments, prioritizing areas of the codebase that change frequently.
• Ensure new code follows strict mode standards while legacy parts remain untouched until needed.

The script we used can be found here: AnnotateErrors

Enforcing Strict Mode Over Time

With our comments in place, we established a set of simple but effective rules to ensure that the transition to strict mode happened gradually without disrupting development:

• If a developer needed to modify a file that contained @ts-expect-error annotations, they were encouraged to remove or fix them whenever possible.
• Any newly written code had to fully comply with strict mode rules from the start, ensuring that the project didn't accumulate new technical debt.
• As developers worked on different parts of the codebase, they could prioritize fixing type issues in frequently updated areas while leaving stable, rarely touched files alone.

This approach allowed us to enforce strict mode without requiring a massive cleanup effort upfront. Over time, the number of @ts-expect-error annotations naturally decreased as developers made improvements while working on features or bug fixes.

Bellow an example of annotated code: