The migration I led took a 400,000-line JavaScript checkout and order system to strict TypeScript over about eighteen months, with no feature freeze and no long-lived branch. We shipped every day of it. The type-level techniques in this course matter, but on a real codebase the process decides whether a migration finishes. This lesson is that process, plus how to keep type-checking fast once you are done.
\nStart by letting TypeScript and JavaScript live together:
\n{\n \"compilerOptions\": {\n \"allowJs\": true,\n \"checkJs\": false,\n \"noEmit\": true,\n \"strict\": true,\n \"module\": \"esnext\",\n \"moduleResolution\": \"bundler\",\n \"target\": \"es2022\",\n \"skipLibCheck\": true\n },\n \"include\": [\"src\"]\n}allowJs brings .js files into the program, so .ts files can import them and vice versa. noEmit leaves building to the existing bundler; tsc --noEmit runs in CI only as a checker. And strict is on from day one, but it only applies to .ts files, so new code is held to the full standard while old code is left alone. Merge this on main in a single small pull request. Nothing about the app changes.
You can get real checking in a .js file without renaming it. Add // @ts-check at the top, and TypeScript checks the file, reading types from JSDoc comments:
// @ts-check\n\n/** @typedef {'USD' | 'EUR' | 'EGP'} Currency */\n/** @typedef {{ cents: number; currency: Currency }} Money */\n\n/**\n * @param {Money} a\n * @param {Money} b\n * @returns {Money}\n */\nexport function add(a, b) {\n if (a.currency !== b.currency) throw new Error('Currency mismatch');\n return { cents: a.cents + b.cents, currency: a.currency };\n}That is the same checker, with the same rules, on a plain JavaScript file. Use it on the hottest, riskiest files first. JSDoc can even import types from .ts files with @import or import('./types').Order, so a JavaScript file can use the domain types you have already written.
When you do rename files, the order matters. Draw (or generate) the import graph and start at the leaves: modules that import nothing else from your codebase, such as money helpers, formatting, constants and the domain types. Then convert the modules that depend only on converted ones, and keep working inward toward the entry points.
\nConverting an entry point first gives you a .ts file whose imports are all untyped, which means a lot of any and very little checking. Converting a leaf first gives every later file real types to build on.
Alongside the leaves, prioritise the boundaries: the API client, the parsers, the domain models. A typed Order and a parsed API response protect every file that touches them, converted or not. That is why sections 1, 2 and 4 of this course matter more for a migration than section 3.
When the last .js file is gone, remove allowJs. Then ratchet up the extra flags from tsconfig Strictness That Pays Off, noUncheckedIndexedAccess first, one at a time, suppressing existing errors with // @ts-expect-error and a ticket so new code meets the bar immediately.
On a large codebase, type-checking speed becomes a developer-experience problem. Measure before you guess: tsc --noEmit --extendedDiagnostics prints check time, memory and the number of type instantiations. A sudden jump in instantiations almost always comes from a heavy type-level utility, like the recursive Paths from Recursive Types and Knowing When to Stop, applied to a big type. --generateTrace <dir> records where the time goes, file by file.
The structural fixes are well established. Turn on incremental so unchanged files are not re-checked. Split a large repository into project references (composite: true in each package, tsc -b at the root), so each part is checked once and its declarations reused. Prefer interfaces that extend each other over long chains of & intersections for big object types, since the compiler caches interface relationships more effectively. And annotate the return types of exported functions, which saves the checker from re-inferring them and keeps declaration output stable.
You have used types to design states, steered inference, written type-level code with restraint, built the patterns real codebases rely on, and set up the compiler to back them. The habit to keep is the one from the first lesson: before you write a type, name the bug it prevents. Then pick the simplest type that prevents it. The exercise below puts the migration playbook in order; the final assessment covers the whole course.
\n","toc":[{"id":"sec-1","text":"Coexist first","level":2},{"id":"sec-2","text":"Check JavaScript before converting it","level":2},{"id":"sec-3","text":"Convert from the leaves inward","level":2},{"id":"sec-4","text":"Keeping it fast","level":2},{"id":"sec-5","text":"Where to go from here","level":2}],"takeaways":["Migrate incrementally withallowJs, so JavaScript and TypeScript files live side by side and the app ships every day.","// @ts-check plus JSDoc types gives a JavaScript file real checking before you rename it.","Convert leaf modules first and work toward the entry points, so each newly converted file imports typed code.","Type the boundaries (API responses, domain models) early; they give the most protection per hour spent.","Measure type-checking with --extendedDiagnostics, use incremental builds and project references, and keep heavy type-level code out of hot paths."],"further":[{"title":"Migrating from JavaScript","url":"https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html"},{"title":"JSDoc Reference","url":"https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html"},{"title":"Project References","url":"https://www.typescriptlang.org/docs/handbook/project-references.html"},{"title":"Type Checking JavaScript Files","url":"https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html"}],"quiz":[{"q":"You are starting a migration of a 1,500-file JavaScript app. Which first step keeps the app shippable?
","options":[{"text":"Create a long-livedtypescript branch and rename every file to .ts there.","why":"A big-bang branch drifts from main daily and merges into a wall of conflicts and errors. Teams that try it often abandon it."},{"text":"Rename every file to .ts on main and add // @ts-nocheck to each one.","why":"This creates thousands of files that look typed but check nothing, and removing the directive later is the same big-bang problem."},{"text":"Wait until the team has time to convert everything in one sprint.","why":"That sprint never comes for a codebase this size; incremental work is the only approach that finishes."},{"text":"Add a tsconfig with allowJs, run tsc --noEmit in CI, and convert files one at a time on main.","why":"Correct. JavaScript and TypeScript coexist, every pull request ships, and the converted share only goes up."}],"answer":3},{"q":"In which order should you convert modules?
","options":[{"text":"Entry points first, so the most visible code is typed.","why":"Entry points import everything else; converted early, they import untyped modules and get mostlyany."},{"text":"Leaf modules (those that import nothing internal) first, then the modules that depend on them.","why":"Correct. Each converted file then imports code that is already typed, so its own types are real from day one."},{"text":"Alphabetically, so progress is easy to track.","why":"File names say nothing about dependencies; you would often convert a file before the code it relies on."}],"answer":1},{"q":"tsc --extendedDiagnostics shows 9 million type instantiations, most from one file. What is the likely cause?
any annotations.","why":"Adding any hides the problem by removing checking, which is not a fix."}],"answer":0},{"q":"How does // @ts-check at the top of a .js file help a migration?
tsc emit a .d.ts file for that module.","why":"Declaration output depends on declaration settings, not on @ts-check."},{"text":"It type-checks that JavaScript file, using JSDoc comments for types, so you can find bugs before renaming it.","why":"Correct. JSDoc annotations like @param {Order} order are real types to the checker, with no build changes."}],"answer":2}],"exercise":{"kind":"order","items":["add-tsconfig","check-boundaries","convert-leaves","convert-inward","drop-allowjs","ratchet-flags"],"title":"Put the migration playbook in order","prompt":"Cartwheel’s order-management app is 1,500 JavaScript files and must keep shipping every day. Put these migration steps in the order the lesson recommends, from the first pull request to the last.
\n","hints":["The very first step changes nothing about how the app is built or run.","You can get type checking in JavaScript files before renaming any of them.","Converted files should import code that is already typed, and the extra strictness flags come once everything is TypeScript."],"explanation":"First, a tsconfig with allowJs and noEmit, checked in CI, lets both languages coexist without touching the build. Next, // @ts-check and JSDoc on the boundaries (API client, domain models) give the most protection before any renaming. Then convert leaf modules, and work inward, so each converted file imports typed code. When no .js source remains, drop allowJs. Finally, ratchet up extra flags such as noUncheckedIndexedAccess one at a time, suppressing existing errors with @ts-expect-error and a ticket so new code meets the higher bar immediately.
allowJs, noEmit and strict, and run tsc --noEmit in CI next to the existing build","check-boundaries":"Add // @ts-check and JSDoc types to the API client and domain model files","convert-leaves":"Rename leaf modules (helpers that import nothing internal) from .js to .ts","convert-inward":"Convert the modules that depend on already-converted ones, working toward the entry points","drop-allowjs":"Remove allowJs once no .js source files remain","ratchet-flags":"Turn on noUncheckedIndexedAccess and other extra flags one at a time, marking old errors with @ts-expect-error"}},"words":830,"readMinutes":4}