Combining allowJs, checkJs, and Incremental Migration
You'll learn how to use allowJs and checkJs together as a powerful migration strategy that lets you type-check JavaScript files before converting them to TypeScript.
The Layered Safety Approach
Think of migrating a large codebase like renovating a house while people still live in it. You can't rip everything out at once. allowJs and checkJs together create a "construction zone" where you can verify safety without requiring full demolition.
Here's how they work as stepping stones:
Step 1: allowJs only — TypeScript compiles your .js files but doesn't type-check them. You can import JS from TS and vice versa. This is your foundation: everything still runs.
Step 2: allowJs + checkJs — Now TypeScript type-checks your JavaScript files using inference and JSDoc comments. You discover issues before converting to .ts.
Step 3: Selective .ts conversion — Armed with insights from checkJs, you convert stable, well-understood files to TypeScript one at a time.
Why This Combination Works
When you enable both flags, you get:
- Immediate feedback on type errors in JavaScript without changing file extensions
- Gradual fixes using JSDoc annotations where needed
- Confidence that converting to
.tswon't introduce surprises - Team velocity — developers can keep shipping features while migration happens
The key insight: checkJs exposes the gaps in your mental model of the code's types. Fix those gaps with JSDoc or inline changes, then rename to .ts when the file is clean.
Key Takeaway: Using allowJs and checkJs together transforms migration from a risky "big bang" rewrite into a safe, incremental journey where each JavaScript file gets type-checked before becoming TypeScript, letting you catch issues early and convert files only when they're ready.