Setting Up for Incremental Migration
What you'll learn: How to configure your TypeScript compiler to safely run JavaScript and TypeScript side-by-side while gradually increasing type safety.
The Migration Configuration
When migrating a JavaScript codebase to TypeScript, you don't want to convert everything at once. Instead, you need a compiler configuration that allows both languages to coexist peacefully while you work file-by-file.
The key is setting up tsconfig.json to be permissive enough to compile JavaScript but strict enough to catch real errors as you add types.
Essential Configuration for Coexistence
At minimum, your tsconfig.json needs:
{
"compilerOptions": {
"allowJs": true,
"checkJs": false,
"strict": false,
"noImplicitAny": false,
"target": "ES2020",
"module": "commonjs",
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
allowJs: true — This is your foundation. It tells TypeScript "yes, compile .js files too, not just .ts files." Without this, TypeScript will ignore your existing JavaScript entirely.
checkJs: false — Initially keep this off. Your JavaScript wasn't written with types in mind, and enabling checking immediately would flood you with errors. You can selectively enable checking file-by-file using @ts-check comments.
strict: false — Start permissive. Enabling strict mode on a JavaScript codebase would be overwhelming. You'll tighten this gradually.
The Incremental Strictness Plan
Think of strictness flags as a dial you turn up slowly:
Phase 1 (where you start):
strict: falsenoImplicitAny: false
Phase 2 (after some files are converted):
noImplicitAny: true- Still
strict: false
Phase 3 (majority converted):
strict: true
This way, newly converted TypeScript files benefit from stricter checking while old JavaScript files continue to work.
Tracking What's Left
Consider adding comments or a separate tracking document for which files remain JavaScript. Some teams use naming conventions or directory structures to visualize migration progress.
Key Takeaway: Incremental migration requires allowJs: true to compile both languages together, with strictness flags initially disabled and gradually tightened as you convert files, creating a safe path from JavaScript to fully-typed TypeScript.