Migrating Javascript To Typescript

The Slow Death of Untyped JavaScript

We've all inherited the codebase where every variable is a guessing game. You open a file and see const data = response; with no context. Is data an object? An array? null? You add a feature, everything breaks, and you spend three days bisecting runtime errors that TypeScript would have caught in seconds.

Manual migration is a trap. You start with // @ts-nocheck on every file, promising to fix it later. Later never comes. The codebase becomes a graveyard of any types, and your CI pipeline turns into a bottleneck of flaky type checks. Engineers lose trust in the tooling because it feels like a chore rather than a safety net. You end up fighting the compiler instead of leveraging it.

We built this skill so you don't have to manually rewrite your legacy code or risk breaking production. It gives you a structured, three-phase path to lock down types without halting feature development. This isn't just about adding a dependency; it's about installing a migration engine that handles the heavy lifting, from configuration to validation.

What Your Codebase Costs When You Delay

Every month you run untyped JavaScript, you pay a tax.

Onboarding new engineers takes twice as long because they have to reverse-engineer data shapes from usage. There's no autocomplete, no inline documentation, and no compiler to tell you when you're passing the wrong arguments. You're relying on tribal knowledge and hope.

Refactoring becomes a game of whack-a-mole. You change a function signature, and the bug report comes in from production three days later because the caller didn't update its destructuring. Runtime errors in production are expensive. A single null-pointer exception in a payment flow can cost thousands in refunds and support tickets.

TypeScript's strict mode catches these before they ship ^[4]. But setting it up correctly requires more than just npm install typescript. You need a strategy that handles declaration files, class migration, and compiler flags without introducing regressions ^[1]. If you're starting fresh or need to streamline your initial setup, check out Setting Up Typescript Project to get the foundation right.

A Hypothetical Fintech App's Migration Nightmare

Imagine a fintech team with 50,000 lines of JavaScript. They decide to migrate to TypeScript to satisfy a new security audit. They start by converting files one by one. Within a week, they're drowning in compiler errors.

Class properties are missing initializers. Generators are yielding undefined values. Exports are untyped. They try to force it by adding any to every function signature. The compiler shuts up, but the type safety evaporates. They declare victory, but the underlying risk remains.

A better approach exists. Tools like ts-migrate can automate the heavy lifting of class and function conversion ^[1]. By separating input and output files during the migration, you prevent TypeScript from overwriting your source while you iterate ^[5]. This separation is critical; it lets you run the compiler in strict mode on the output while keeping your source intact.

Once the tooling is in place, you can enforce strictness incrementally. You don't have to convert everything at once. You can migrate module by module, validating each step. For teams needing a broader migration strategy, the TypeScript Migration Pack offers a deeper dive into automation and validation.

What Happens Once the Migration Is Locked

With this skill installed, your migration stops being a guesswork exercise and becomes a repeatable pipeline.

You get a production-grade tsconfig.json that enforces strict mode, isolated declarations, and exact optional property types. The ts-migrate tool runs automatically, converting your JS classes and functions while preserving logic. You get validation scripts that audit your codebase for anti-patterns. If a developer introduces an any type, the build fails.

Declaration files are generated from your JavaScript sources, giving you documentation and type checking for legacy code ^[6]. You can refactor with confidence. When you change a function signature, the compiler tells you exactly which callers need updating. Errors like TS2564 (missing property initialization) or TS2322 (type mismatch) are resolved systematically, not patched over ^[4].

This is the difference between a migration that fails and one that ships. You stop fearing changes and start embracing them.

What's in the Migrating Javascript To Typescript Skill

• skill.md — Orchestrator skill that defines the three-phase migration strategy (Configure, Migrate, Improve), references all templates, scripts, validators, and references, and guides the agent through the end-to-end process.
• templates/tsconfig.json — Production-grade TypeScript configuration enabling strict mode, declaration generation, isolated declarations, and exact optional property types. Serves as the baseline for the migration.
• templates/ts-migrate-config.json — Configuration for Airbnb's ts-migrate tool, defining file patterns, class migration rules, and plugin settings for automated JS-to-TS conversion.
• scripts/migrate.sh — Executable migration runner that invokes ts-migrate, runs the TypeScript compiler in strict mode, captures errors, and exits non-zero if migration fails or introduces regressions.
• scripts/generate-decls.py — Python script using the TypeScript Compiler API to generate .d.ts declaration files from JavaScript sources, enabling type checking and documentation for legacy code.
• validators/check-strictness.sh — Validator script that audits the codebase for migration anti-patterns (e.g., excessive 'any' usage, missing explicit return types, untyped exports) and exits non-zero on failure.
• references/compiler-options.md — Canonical reference for TypeScript compiler flags relevant to migration, including strict, isolatedDeclarations, exactOptionalPropertyTypes, and declaration, with dependency rules and error contexts.
• references/type-checking-errors.md — Reference for common TypeScript compiler errors encountered during migration (TS2564, TS2322, TS9012, TS9007, TS5052), with causes and fixes grounded in compiler behavior.
• references/declaration-generation.md — Guide to generating declaration files from JavaScript using the TypeScript Compiler API, including programmatic setup, in-memory emission, and verification logic.
• references/phase-strategy.md — Detailed breakdown of the three-phase migration approach: Configure build tools, Migrate code using ts-migrate and manual fixes, Improve by enforcing strictness and generating declarations.
• examples/worked-example.ts — Worked example of a migrated TypeScript module demonstrating strict class property initialization, generator yield type checking, and explicit return types.
• examples/tsconfig-strict.json — Extended tsconfig example that inherits base settings and enforces strict null checks and isolated declarations for production builds.

Stop Guessing, Start Migrating

Don't let your codebase rot. Upgrade to Pro to install this skill and lock down your types today.

We built this so you can migrate with confidence, not fear. Your future self will thank you.