allowJs: Mixing JavaScript and TypeScript Files
What you'll learn: How to enable TypeScript and JavaScript files to coexist peacefully in the same project during migration.
The Coexistence Problem
When migrating a JavaScript codebase to TypeScript, you face an immediate challenge: you can't realistically convert everything at once. You need a way for .ts files to import from .js files, and vice versa, without the compiler rejecting your half-migrated project.
By default, the TypeScript compiler only processes .ts and .tsx files. If you try to import a .js file from a .ts file, TypeScript won't even look at it—it'll treat the import as referring to a missing module.
What allowJs Does
The allowJs compiler option tells TypeScript: "Process JavaScript files too, not just TypeScript files."
When enabled, the TypeScript compiler will:
- Type-check your
.jsfiles (to the extent possible without explicit types) - Allow
.tsfiles to import from.jsfiles - Include
.jsfiles in the compilation output (copying or transforming them based on your target settings)
Think of it as opening a door between two rooms: your TypeScript code can now see and work with your existing JavaScript code.
Enabling allowJs
In your tsconfig.json:
{
"compilerOptions": {
"allowJs": true,
"outDir": "./dist"
},
"include": ["src/**/*"]
}
Now both .js and .ts files in src/ will be processed together.
The Migration Bridge
This option is the foundation of gradual migration. You can:
- Keep existing
.jsfiles running while you incrementally convert them - Import JavaScript modules from your new TypeScript code
- Work file-by-file without breaking your entire build
Key Takeaway: allowJs is the essential bridge for gradual TypeScript adoption, allowing JavaScript and TypeScript files to coexist and interoperate in the same project while you migrate incrementally.