Setting Up a Dual-Mode Project
You'll learn how to configure TypeScript's compiler to work alongside existing JavaScript files, enabling a gradual migration path rather than a big-bang rewrite.
Why Dual-Mode Matters
When migrating a JavaScript codebase to TypeScript, you rarely want to convert everything at once. A dual-mode project allows .js and .ts files to coexist in the same codebase, with TypeScript understanding both. This lets you migrate file-by-file, testing incrementally as you go.
Think of it like renovating a house room-by-room while still living in it—you don't need to move out and rebuild everything from scratch.
The allowJs Flag
The key to dual-mode is the allowJs compiler option in your tsconfig.json. This tells TypeScript to process JavaScript files as part of the compilation, not just ignore them:
{
"compilerOptions": {
"allowJs": true,
"target": "ES2020",
"module": "commonjs",
"outDir": "./dist",
"strict": false
},
"include": ["src/**/*"]
}
With allowJs: true, TypeScript will:
- Type-check your
.jsfiles using inference - Allow
.tsfiles to import from.jsfiles - Compile both to your output directory
Initial Configuration Strategy
Start with less strict settings during migration:
{
"compilerOptions": {
"allowJs": true,
"checkJs": false, // Don't type-check .js files yet
"strict": false, // Relax strict mode initially
"noEmit": false, // Allow output generation
"esModuleInterop": true,
"skipLibCheck": true
}
}
As you convert files, gradually enable stricter checking. Once a file becomes .ts, it benefits from your chosen strictness level.
Migration Workflow Example
- Start:
user.jsanddatabase.jsboth JavaScript - Convert one: Rename
user.js→user.ts, add types - Imports work:
database.jscan still import fromuser.ts - Coexistence: Both compiled to
dist/together - Iterate: Convert
database.jsnext, repeat
This gradual approach means your codebase stays functional throughout the entire migration.
Key Takeaway: The allowJs flag enables dual-mode projects where JavaScript and TypeScript files coexist, with checkJs and strict flags controlling how aggressive type-checking is during migration. This configuration is the foundation for incremental, safe TypeScript adoption.