Course contentsShow
← TypeScript
Lesson 1615 of 1,79637. Migrating JavaScript to TypeScriptFree lesson

Setting Up for Incremental Migration

Configuring tsconfig with allowJs and appropriate strictness flags to enable gradual JavaScript coexistence.

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: false
  • noImplicitAny: 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.