ts-migrate

Migrate JavaScript code to TypeScript with step-by-step guidance:

1. Analyze Migration Scope

   • If $ARGUMENTS provided, use as file pattern to migrate
   • Otherwise, analyze entire project:
     • Count JS vs TS files
     • Identify dependencies between files
     • Determine migration complexity
     • Calculate estimated effort
   • Create dependency graph to determine migration order

2. Plan Migration Strategy

   • Order of Migration:
     1. Type definition files (create .d.ts)
     2. Utility functions and constants
     3. Leaf modules (no internal dependencies)
     4. Core business logic
     5. React components (if applicable)
     6. Main application files
   • Show migration plan with file groups
   • Identify high-risk files (complex, many dependencies)

3. Prepare Environment

   • Check if TypeScript is installed
   • Review tsconfig.json settings (should be permissive initially)
   • Ensure allowJs: true for gradual migration
   • Set up @types packages for dependencies
   • Create custom type declarations for untyped libraries

4. Migrate Files One by One

   For each file in migration order:

   Step A: Rename & Basic Typing

   • Rename .js → .ts (or .jsx → .tsx)
   • Add explicit return types to functions
   • Type function parameters
   • Type variable declarations where needed

   Step B: Convert Patterns

   • PropTypes → TypeScript interfaces (React)
   • JSDoc types → TypeScript annotations
   • require() → import statements (if needed)
   • module.exports → export statements

   Step C: Handle Type Issues

   • Resolve implicit any errors
   • Add type guards for dynamic code
   • Type event handlers correctly
   • Handle null/undefined properly

   Step D: Improve Type Safety

   • Replace any with specific types
   • Add union types for multiple possibilities
   • Use discriminated unions for state
   • Add readonly for immutability

   Step E: Verify

   • Run type checker: tsc --noEmit
   • Fix any type errors
   • Ensure tests still pass
   • Verify build succeeds

5. Handle Common Migration Challenges

   Dynamic Property Access:

   // Before
   function getValue(obj, key) {
     return obj[key];
   }
   
   // After
   function getValue<T, K extends keyof T>(obj: T, key: K): T[K] {
     return obj[key];
   }
   

   Mixed Return Types:

   // Before
   function getUser(id) {
     if (!id) return null;
     return fetchUser(id);
   }
   
   // After
   function getUser(id: number | undefined): Promise<User> | null {
     if (!id) return null;
     return fetchUser(id);
   }
   

   Untyped Libraries:

   // Create ambient declaration
   // types/my-library.d.ts
   declare module 'my-library' {
     export function doSomething(arg: string): number;
   }
   

6. Track Progress

   • Show percentage of files migrated
   • Count remaining JS files
   • List next files to migrate
   • Estimate remaining effort

7. Post-Migration Cleanup

   • Remove PropTypes dependencies
   • Delete unnecessary @ts-ignore comments
   • Remove redundant type assertions
   • Update build scripts (remove Babel if using tsc)
   • Update documentation

8. Gradual Strict Mode Adoption

   • After basic migration, suggest enabling strict flags
   • Recommend using /ts-strict command
   • Set timeline for full strict mode adoption

9. Create Migration Report

   • Files migrated count
   • Type errors resolved count
   • Remaining TODOs
   • Suggested next steps
   • Breaking changes (if any)

Examples:

• /ts-migrate - Migrate entire project
• /ts-migrate src/components/*.js - Migrate specific files
• /ts-migrate --dry-run - Show plan without changes
• /ts-migrate src/utils - Migrate directory

The migration will be incremental, safe, and preserve all functionality while adding type safety.