How to Do TypeScript Migration on Claude Code

March 16, 2026

Claude Code can handle a JavaScript-to-TypeScript migration end-to-end: renaming files, inferring types from usage, adding interfaces, and fixing compiler errors in batches. It works best on medium-to-large codebases where doing this by hand takes days. Run the migration in stages so Claude stays within context limits and you can review diffs incrementally.

TypeScript adoption is at an all-time high, with TypeScript ranking as the 5th most-used language in the 2024 Stack Overflow Developer Survey.
A typical migration of a 10,000-line JS codebase involves hundreds of individual file edits and type annotations, making AI-assisted tooling a practical necessity.
Claude Code uses extended context to hold your entire file graph in view, catching cross-file type inconsistencies that simpler tools miss.

What does a TypeScript migration on Claude Code actually look like?

A TypeScript migration is not a single command. It is a structured sequence: configure the compiler, rename files, add types, and iterate on errors. Claude Code accelerates every step by letting you describe intent in plain language and having it apply changes across multiple files simultaneously, without leaving your terminal.

The key is breaking the migration into phases so each Claude Code session has a focused scope. Trying to migrate everything in one prompt will exhaust your usage window mid-task, which is exactly the kind of 5-hour lockout you want to avoid when you are halfway through a PR.

How to set up your project before starting the migration

Before writing a single prompt, make sure the scaffolding is in place:

Initialize a tsconfig.json with npx tsc --init and set "allowJs": true and "checkJs": false to start permissively.
Add TypeScript as a dev dependency: npm install --save-dev typescript.
Commit your current state to git so every Claude-generated diff is reviewable and reversible.
Identify the migration order: shared utilities and types first, then leaf modules, then entry points.

This setup lets you migrate incrementally rather than in a big-bang rewrite, which is the approach recommended in the official TypeScript migration handbook.

Step-by-step: running the migration with Claude Code

Step 1 - Rename files from .js to .ts

Start with a targeted prompt for a single directory:

Rename all .js files in src/utils to .ts. Do not change any code yet, just the extensions.

Claude Code will use shell commands to batch-rename files and confirm what changed. Review the diff before moving on.

Step 2 - Add type annotations to function signatures

Once files are renamed, ask Claude to add types based on how functions are called:

Look at how each function in src/utils is called across the codebase and add TypeScript parameter and return types. Use `unknown` where you cannot infer confidently. Do not change logic.

The instruction to use unknown over any is important. It forces explicit narrowing later and keeps your migration honest. You can also use Claude Code custom commands to encode this rule once and reuse it across sessions.

Step 3 - Create shared interfaces and type files

For data models passed between modules, ask Claude to extract interfaces:

Identify all object shapes that are passed between more than one module in src/. Create a src/types.ts file with TypeScript interfaces for each. Then update imports across the codebase to use them.

This is where Claude Code's multi-file awareness pays off. It can trace how a plain object flows from an API response through three layers of handlers and propose a single coherent interface.

Step 4 - Run the compiler and fix errors in batches

Run npx tsc --noEmit and pipe the output back to Claude:

Here is the output of `tsc --noEmit`. Fix the first 20 errors. Prioritize errors in src/utils before touching src/api.

Batching by count (not by file) keeps each session focused. You can track progress with the Claude Code /usage command and pause at natural checkpoints before your window resets. This matters because tsc output can generate hundreds of errors at once and sending them all in one prompt is wasteful.

Step 5 - Enable stricter compiler options incrementally

Once baseline errors are resolved, tighten the config one flag at a time:

Enable `"strict": true` in tsconfig.json. Run tsc and fix the new errors in src/utils only.

Strict mode catches null safety issues and implicit any that lenient mode misses. Migrating directory by directory means you always have a compiling codebase to ship if needed.

Useful Claude Code slash commands for TypeScript work

Claude Code's slash commands and built-in tools speed up the migration loop:

/review - Ask Claude to review a file for type safety issues before committing.
/usage - Check how much of your usage window remains so you can plan which phase to tackle next without hitting a mid-session cutoff.
Custom slash commands - Define a /migrate-file command in your project's .claude/commands/ directory that encodes your team's migration conventions (prefer unknown, avoid any, always add JSDoc, etc.).

See the full Claude Code slash commands list for a reference of built-in options.

How to handle the usage limit problem during long migrations

TypeScript migrations are session-heavy. You will run multiple Claude Code sessions over hours or days. The worst outcome is hitting your usage cap in the middle of a complex refactor, with half the files updated and the codebase in a broken state.

This is exactly what Usagebar prevents. It sits in your macOS menu bar and shows your Claude Code usage in real time, with smart alerts at 50%, 75%, and 90% of your limit. You know before you hit the wall, not after.

Alerts at 50%, 75%, and 90% so you can wrap up a phase cleanly before running out.
Shows exactly when your usage window resets, so you can plan the next migration session in advance.
Credentials stored securely in macOS Keychain, no third-party servers.
Pay what you want, including a free option for students.

Knowing your remaining capacity means you can confidently start a 20-file batch without worrying about hitting a 5-hour lockout halfway through fixing compiler errors on a Friday afternoon before a deploy.

Get Usagebar - instant download, flexible pricing.

Common migration pitfalls and how Claude Code handles them

Pitfall	What goes wrong manually	How Claude Code helps
Implicit `any` spreading	One untyped function contaminates all callers	Traces call graph and flags all affected sites
Third-party library types	Missing `@types/` packages cause confusing errors	Identifies missing `@types` and suggests install commands
Dynamic object shapes	Objects built with bracket notation resist static typing	Proposes mapped types or index signatures
Inconsistent null checks	Strict null checks expose dozens of latent bugs at once	Fixes in batches with consistent narrowing patterns

Key takeaways

Set up tsconfig.json with allowJs: true and commit before touching any files.
Migrate directory by directory, not all at once, to keep diffs reviewable.
Use Claude Code prompts to rename files, infer types from usage, and extract shared interfaces.
Pipe tsc --noEmit output to Claude and fix errors in batches of 20 or fewer.
Enable strict mode incrementally, one directory at a time.
Monitor your Claude Code usage window with Usagebar to avoid hitting the cap mid-migration.

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar