How to Migrate to TypeScript with Claude Code

February 2026 • 8 min read

Migrating a JavaScript codebase to TypeScript is one of those tasks that everyone agrees is worth doing and nobody wants to start. It is tedious, file-by-file work that touches every part of your project. The type errors cascade, the imports break, and the sheer volume of changes makes it feel like a months-long commitment. Claude Code turns this from a drawn-out slog into a focused sprint. It reads your JavaScript, infers types from actual usage patterns, generates proper interfaces, and converts files one by one -- all while keeping your app running and your tests passing.

Why Claude Code Is Perfect for TypeScript Migration

Most migration tools give you a mechanical rename and a sea of any types. Claude Code is fundamentally different because it actually reads and understands your code. It traces how every function is called, what shapes your objects take, and where data flows between modules. From that understanding, it generates real types -- proper interfaces with specific fields, union types where values vary, and generics where patterns repeat.

Claude Code understands the entire migration path. It knows that .js files become .ts and .jsx files become .tsx. It knows to update your imports, adjust your build configuration, and handle the subtle differences between CommonJS and ES module type declarations. It can start you on a gradual path with allowJs and checkJs enabled, or go straight to strict mode if you prefer to rip the bandage off.

The real advantage is multi-file awareness. When you ask Claude Code to convert a service file, it does not look at that file in isolation. It examines every caller, every consumer, every test that touches that module. The interfaces it generates are consistent across your entire codebase, not just locally correct within a single file. This is the kind of holistic understanding that makes the difference between a migration that works and one that creates more problems than it solves.

The Migration Workspace

A TypeScript migration is a multi-tool operation. You need to convert code, check types, run tests, and verify runtime behavior all at the same time. In Beam, create a workspace called "TS Migration" and set it up with five tabs that cover every angle of the process.

• Tab 1: Claude Code -- this is your conversion engine, where all the migration work happens
• Tab 2: TypeScript compiler -- run tsc --watch --noEmit to see type errors appear and resolve in real-time
• Tab 3: Tests -- your test runner in watch mode, verifying nothing breaks with each conversion
• Tab 4: App -- your application running in development mode so you can verify runtime behavior
• Tab 5: Git -- for committing after each successful file conversion

The most powerful configuration is a split pane with Claude Code on the left and the tsc output on the right. As Claude converts a file, you watch the type errors appear and then resolve in real-time. It is deeply satisfying and gives you immediate confidence that the conversion is correct. Save this layout in Beam so you can restore your entire migration workspace between sessions.

Step 1: Set Up TypeScript

Start the migration by telling Claude Code to scaffold the TypeScript infrastructure. A prompt like "Add TypeScript to this project. Create tsconfig.json with strict mode, configure path aliases to match our existing imports, and update the build pipeline" gives it everything it needs. Claude will install the typescript package, create a properly configured tsconfig.json, and update your package.json scripts to use the TypeScript compiler.

It sets up path aliases that match whatever import patterns you already use. If you have @/components style imports or relative paths that go three directories deep, Claude configures the paths and baseUrl in your tsconfig to match. The critical setting at this stage is allowJs: true, which lets TypeScript and JavaScript coexist in the same project. This is what makes file-by-file migration possible -- you do not have to convert everything at once.

Step 2: Convert File by File

With the infrastructure in place, start converting files. Tell Claude Code something like "Convert src/services/userService.js to TypeScript. Infer proper types from usage, create interfaces for function parameters and return values." Claude renames the file from .js to .ts, analyzes every function signature, and generates typed versions.

What sets Claude Code apart here is that it does not take shortcuts. Instead of slapping any on everything and calling it done, it traces how each function is actually used across your codebase. If getUser always receives a string ID and returns an object with name, email, and role fields, Claude generates an interface that reflects exactly that shape. It looks at your database queries, your API responses, and your test fixtures to figure out the real types.

Keep an eye on your tsc tab while Claude works. You will see type errors appear briefly as the conversion happens, then resolve as Claude adds the right types and updates the imports. Commit each converted file separately. This gives you a clean git history where every commit is a single file conversion, making it easy to bisect if something goes wrong later.

Step 3: Generate Shared Types

After converting a handful of files, you will notice the same shapes appearing in multiple places -- user objects, API responses, configuration types. This is where you ask Claude Code to consolidate. Tell it "Create a types/ directory with shared interfaces for User, Project, Task, and API responses based on how they are used across the codebase."

Claude scans your entire project, identifies the repeated object shapes, and creates centralized type definitions in a dedicated types/ directory. It generates proper type exports and updates every import across your codebase to reference the shared definitions instead of local inline types. This is where Claude saves the most time in the entire migration. Manually finding and consolidating types across dozens or hundreds of files is the kind of work that takes days by hand. Claude does it in minutes because it can hold the entire codebase in context and see every usage pattern at once.

Step 4: Handle the Hard Cases

Claude Code handles these cases with real sophistication. When you point it at a function that accepts any object and returns a transformed version, it generates bounded generics and conditional types that capture the actual transformation logic. Tell it "This function accepts any object and returns a transformed version. Add proper generic types" and watch it produce something like <T extends Record<string, unknown>> with mapped types that preserve the input structure.

For third-party libraries that ship without types and have no @types package on npm, Claude generates custom declaration files. It reads how you use the library throughout your codebase, infers what the API surface looks like, and creates a .d.ts file that gives you proper type checking without modifying the library itself.

Step 5: Enable Strict Mode

Once every file has been converted from JavaScript to TypeScript, it is time to tighten the configuration. Tell Claude Code "Enable strict mode in tsconfig.json and fix all resulting type errors." This flips on the full suite of strict checks: strictNullChecks, strictFunctionTypes, strictPropertyInitialization, noImplicitAny, and more.

Strict mode will surface a new wave of type errors, mostly around nullable values and implicit any types that slipped through during the initial conversion. Claude Code works through these methodically, adding null checks where values might be undefined, narrowing union types with type guards, and replacing any remaining any types with proper definitions. This is the final polish step, and it is exactly the kind of tedious, repetitive work that Claude excels at. What would take a developer hours of manual null-check insertion takes Claude a few minutes.

The Gradual Migration Strategy

• Week 1: Set up TypeScript infrastructure, convert utility files and constants
• Week 2: Convert the service layer -- API clients, database access, business logic
• Week 3: Convert API routes, middleware, and request handlers
• Week 4: Convert components and UI layer (JSX to TSX)
• Week 5: Enable strict mode, final cleanup, remove allowJs

Each week, you open Beam, restore your "TS Migration" workspace layout, and pick up right where you left off. Your Claude Code session, your tsc watcher, your test runner, and your git tab are all exactly where you left them. Beam saves the entire workspace configuration between sessions so there is zero friction resuming the migration after a break.

Memory File: TypeScript Conventions

To keep the migration consistent, especially if multiple developers are involved, create a CLAUDE.md memory file that documents your TypeScript conventions. This file lives in your project root and Claude Code reads it automatically at the start of every session. Include the decisions your team has made so Claude follows them consistently across every file it converts.

• Type naming conventions -- whether you prefix interfaces with I (like IUser) or use plain names (like User), and whether type aliases get a T prefix
• Interfaces vs type aliases -- when to use interface (for object shapes that might be extended) versus type (for unions, intersections, and utility types)
• Strict mode policy -- whether to enforce strict mode from the start or enable it after all files are converted
• Untyped third-party libraries -- whether to create local .d.ts files, use @ts-ignore, or wrap libraries in typed adapters
• Path alias patterns -- your import conventions like @/types, @/services, and how they map to the filesystem

This memory file becomes especially valuable as the migration progresses. Claude Code remembers your conventions between sessions and applies them automatically to every file it touches, producing results that are consistent with the files you converted last week and the ones you will convert next week.

Summary

Migrating to TypeScript does not have to be a months-long ordeal. With Claude Code doing the heavy lifting and Beam keeping your migration workspace organized, you can convert a full codebase in weeks instead of months. The key steps are:

• Set up your migration workspace in Beam with Claude Code, tsc, tests, your app, and git in separate tabs
• Scaffold TypeScript infrastructure with allowJs: true so you can migrate file by file
• Convert files from the leaves inward, committing each conversion separately
• Generate shared types to consolidate repeated shapes across your codebase
• Handle the hard cases -- generics, dynamic objects, untyped libraries -- with Claude's help
• Enable strict mode as the final step and let Claude fix the remaining type errors
• Document conventions in a CLAUDE.md memory file for consistency across sessions

The result is a fully typed, strict-mode TypeScript codebase with proper interfaces, consistent conventions, and a clean git history showing every step of the migration. That is a project you can maintain with confidence.