🔀 typemigrate

Don't just detect breaking API changes — fix them. The only tool that diffs .d.ts exports between package versions and automatically rewrites your code to match.

Features · Quick Start · CLI · How It Works · vs Competitors

✨ Features

| Feature | What It Does | |:--------|:-------------| | 🔍 AST-Level Diffing | Compares exported function signatures between old and new .d.ts files using ts-morph | | ✏️ Auto-Renames | Detects renamed exports by structural signature matching — rewrites imports AND all call sites | | 🗑️ Removed API Handling | Replaces deleted-API call sites with TODO comments so your code still compiles | | 📦 Options-Wrapper Detection | When f(a, b) becomes f({ a, b }), rewrites positional args to object literals | | 🌐 Namespace Import Support | Handles import * as pkg patterns — renames, removals, and signature changes | | 🔗 Deep Re-Export Following | --deep flag follows export { ... } from './sub' into submodules | | ✅ Compilation Verification | Runs tsc --noEmit after refactoring to confirm type safety | | 🎯 Dry-Run Default | Shows what changed without touching files unless you pass --apply | | 📂 Configurable Globs | --glob / --exclude flags + tsconfig.json include fallback | | 🔒 Package Manager Aware | Detects npm/yarn/pnpm/bun — installs temp packages with your PM, copies your lockfile |

🚀 Quick Start

npm install -g typemigrate

# See what changed (safe — no files touched)
typemigrate run [email protected]

# Apply fixes automatically
typemigrate run [email protected] --apply

📖 CLI Reference

typemigrate run <pkg>@<version> [options]

# Dry-run: see what broke
typemigrate run [email protected]

# Full auto-fix with deep re-export following
typemigrate run [email protected] --apply --deep

# Target specific files
typemigrate run [email protected] --apply --glob "src/**/*.tsx" --exclude "**/*.test.tsx"

| Flag | Description | |:-----|:------------| | --apply | Apply AST changes in-place (default: dry-run only) | | --glob <pattern> | Source file glob(s) to process (repeatable) | | --exclude <pattern> | Glob pattern(s) to exclude (repeatable) | | --deep | Follow re-exports into submodules (experimental) |

Example Output

Detected 3 API Changes:
  - [Rename] oldFn -> newFn
  - [Removal] deletedFn (no matching signature found)
  - [Change] processData (signature layout modified: isomorphism:options-wrapper)

🔧 How It Works

┌────────────────────────────────────────────────────────┐
│  1. OLD VERSION                                        │
│  Parse node_modules/<pkg>/index.d.ts with ts-morph     │
│  → Collect all exported function declarations + sigs   │
├────────────────────────────────────────────────────────┤
│  2. NEW VERSION                                        │
│  Temp-install <pkg>@<target> with your PM + lockfile   │
│  → Parse new .d.ts, collect exports + signatures       │
├────────────────────────────────────────────────────────┤
│  3. STRUCTURAL DIFF                                    │
│  Match by name → detect signature changes              │
│  Match by signature → detect renames                   │
│  Unmatched old → register as removal                   │
│  Multi-param → single-obj → detect options-wrapper     │
├────────────────────────────────────────────────────────┤
│  4. AST REFACTORING                                    │
│  Named imports: rename specs + all references          │
│  Namespace imports: single-pass forEachDescendant       │
│  Removed APIs: delete statement + // TODO comment       │
│  Signature changes: prepend // WARNING comment          │
├────────────────────────────────────────────────────────┤
│  5. VERIFY                                             │
│  tsc --noEmit via your package manager                 │
│  → Reports pass/fail + first 10 error lines            │
└────────────────────────────────────────────────────────┘

[!TIP] Lockfile-aware installs. typemigrate copies your lockfile to the temp directory before installing, so transitive dependency versions match what you'd actually get.

🆚 Why typemigrate?

| Tool | Detects Changes | Auto-Fixes Code | Namespace Imports | Options-Wrapper | Re-Export Following | |:-----|:--------------:|:--------------:|:-----------------:|:---------------:|:-------------------:| | typemigrate | ✅ | ✅ | ✅ | ✅ | ✅ | | @grafana/levitate | ✅ | ❌ | ❌ | ❌ | ✅ | | vdiff-mcp | ✅ | ❌ | ❌ | ❌ | ❌ | | @evrys/tsdiff | ✅ | ❌ | ❌ | ❌ | ❌ | | typeversion | ✅ | ❌ | ❌ | ❌ | ❌ |

The difference: @grafana/levitate (10K+ weekly downloads) tells you what broke. typemigrate fixes it for you. Every other tool stops at the diagnostic. typemigrate is the only one that picks up the scalpel and rewrites your code — renames, removals, signature migrations, and even options-wrapper isomorphism detection.

📄 License

MIT · codecrypt112