How to Do TypeScript Conversion on Claude Code

TypeScript conversion in Claude Code means prompting the agent to rewrite JavaScript files with strict types, interfaces, and compiler-safe annotations. It works best file-by-file using /project context and targeted prompts. Conversion tasks can be token-heavy, so Usagebar helps you monitor usage in your macOS menu bar and avoid a mid-conversion lockout.

• Claude Code can convert a single JS file to TS in one prompt, or walk a full codebase incrementally
• Strict mode conversion (enabling strict: true in tsconfig) typically requires 2-4x more back-and-forth than loose conversion
• Usage limits apply per 5-hour rolling window on Pro and Max plans (Anthropic docs)

What is TypeScript conversion and why do it in Claude Code?

TypeScript conversion is the process of migrating .js files to .ts, adding explicit types, replacing any with precise interfaces, and making your codebase pass tsc --noEmit without errors. It is one of the most repetitive, pattern-driven tasks in frontend and backend development, which makes it a strong fit for Claude Code's agentic workflow.

Claude Code holds your project context across files, meaning it can track imported types, infer shapes from usage, and apply consistent naming conventions throughout a codebase, something that takes hours manually. According to Anthropic's documentation, Claude Code is designed for exactly these kinds of multi-file, multi-step engineering tasks on Pro and Max plans.

How to set up your project before starting the conversion

Before issuing any conversion prompts, get your repo and TypeScript config in place. Claude Code works best when it can see the full project structure and a tsconfig.json already exists.

• Initialize TypeScript: npx tsc --init if you don't have a tsconfig yet
• Set "allowJs": true and "checkJs": false initially so unconverted files don't block the build
• Install type packages your project needs: npm i -D @types/node @types/react etc.
• Open Claude Code in your project root so it has full file-tree access
• Run /project to confirm Claude Code has indexed your workspace

This setup phase prevents Claude Code from guessing your target tsconfig strictness mid-task, which wastes tokens and triggers correction loops. See the guide on reducing Claude Code token usage for more strategies before starting a heavy refactor.

Step-by-step: how to run a TypeScript conversion with Claude Code

Step 1 – Start with a single file to establish a pattern

Never convert an entire codebase in one prompt. Start with a leaf file (no local imports) so Claude Code produces a clean, reviewable output with no cascading type errors.

Example prompt:

Convert src/utils/formatDate.js to TypeScript. Add explicit return types and parameter types. Do not use 'any'. Export a DateFormatOptions interface if needed.

Step 2 – Use /add to scope context precisely

Claude Code's /add slash command lets you pin specific files to the context window. For conversion tasks, add both the JS source and any related test file:

/add src/services/userService.js src/services/__tests__/userService.test.js

This keeps Claude Code focused and avoids it pulling in unrelated files that inflate token usage.

Step 3 – Request a strict-mode conversion with explicit constraints

Once your pattern file looks good, apply the same approach to business logic files. Be explicit about strictness:

Convert src/services/userService.js to TypeScript with strict mode compatibility. Replace all implicit 'any' types. Define interfaces for all function parameters and return values. Rename the file to .ts.

Step 4 – Handle third-party types inline

For libraries without DefinitelyTyped support, ask Claude Code to generate a local declaration file:

The package 'legacy-chart-lib' has no @types. Create a src/types/legacy-chart-lib.d.ts with the minimal type declarations needed to compile our usage in src/components/Chart.js.

Step 5 – Validate after each batch

After converting a module or directory, run npx tsc --noEmit and paste any errors back into Claude Code:

Here are the tsc errors after converting the services directory. Fix them: [paste errors]

This tight feedback loop is faster than prompting for the whole fix upfront and keeps each Claude Code response focused and under token limits.

Step 6 – Use /usage to check remaining capacity

TypeScript conversion on a medium-sized codebase (50-150 files) can span multiple sessions. Run /usage in Claude Code at any point to see where you stand in your current 5-hour window. You can also check claude.ai/settings/usage for a full breakdown. If you are on macOS, Usagebar shows your live usage percentage in the menu bar with alerts at 50%, 75%, and 90% so you never hit a wall mid-file.

How to handle common TypeScript conversion patterns in Claude Code

Pattern	Prompt approach	Watch out for
Object spread / rest	Ask for Partial<T> or Pick<T> usage	Overly broad Record<string, unknown> fallbacks
Callback-heavy code	Request typed callback signatures explicitly	Claude defaulting to (cb: Function)
Dynamic property access	Ask Claude to use index signatures or mapped types	Silent any inserted for bracket notation
React components (JSX)	Specify FC<Props> or plain function with explicit return type	Missing children: React.ReactNode in props
Express route handlers	Ask for Request, Response, NextFunction imports from express	Missing @types/express install step

For projects already using Prisma, the schema often drives the type layer. See the guide on Prisma schema migration with Claude Code for how to connect generated types to your converted TypeScript files.

How to avoid hitting usage limits during a large TypeScript conversion

Large conversions are among the most token-intensive tasks in Claude Code. A 100-file JavaScript project can easily consume a substantial portion of a Pro plan's 5-hour window, especially if you're iterating on type errors. Here's how to stay in flow:

• Convert in modules, not files: Group files by directory and convert them together to reduce context reloading between prompts
• Commit after each batch: This lets you resume across sessions without re-explaining what was already converted
• Use /clear between unrelated modules: Clearing the context window prevents Claude Code from accumulating stale type information that leads to contradictions
• Monitor usage proactively: Check /usage regularly, or use Usagebar on macOS for persistent menu bar visibility with smart alerts before you hit limits

The worst outcome is getting locked out mid-conversion with a half-typed codebase that won't compile. The usage reset timer on Claude Code follows a rolling 5-hour window, so knowing exactly when it resets helps you plan your conversion sessions around it.

Related: How to reduce Claude Code token usage covers prompt strategies that apply directly to conversion tasks.

TypeScript conversion vs. TypeScript migration: what's the difference?

These terms are often used interchangeably, but in Claude Code workflows there is a practical distinction. Conversion refers to rewriting individual files from JS to TS with types added. Migration refers to the broader project-level process: updating build tooling, adjusting module resolution, enabling stricter compiler flags incrementally, and updating CI/CD pipelines. For the broader migration workflow, see the TypeScript migration guide for Claude Code.

If your goal is also to generate shared interfaces from your data layer, the TypeScript interface generation guide covers how to use Claude Code to produce reusable type definitions from API responses, database schemas, and config objects.

Key takeaways

1. Start with a single leaf file to establish a type pattern before converting whole directories
2. Use /add to scope context to the files being converted, not the whole project
3. Run npx tsc --noEmit after each batch and feed errors back to Claude Code immediately
4. Use explicit prompts: specify strict mode, no any, named interfaces, and file rename
5. Track usage with /usage or via Usagebar's macOS menu bar alerts to avoid a mid-conversion lockout
6. Commit after each converted module so sessions are resumable without context loss

Monitor your usage while you convert

TypeScript conversion is exactly the kind of deep, focused work where a usage interruption is most disruptive. You are mid-file, mid-type-chain, and a 5-hour lockout means picking up a half-compiled codebase from scratch in the next session.

Usagebar sits in your macOS menu bar and shows your Claude Code usage in real time. It sends alerts at 50%, 75%, and 90% so you can wrap up a conversion batch cleanly before the limit hits. Credentials are stored in macOS Keychain and the app is pay-what-you-want with a free option for students. Get Usagebar at usagebar.com and keep your conversion sessions in flow.

Sources

• https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan
• https://code.claude.com/docs/en/slash-commands
• https://claude.ai/settings/usage