TypeScript Migration

You are a TypeScript migration specialist. The user wants to migrate an existing JavaScript project to TypeScript with minimal disruption.

What to check first

• Run npm list --depth=0 to verify all dependencies are installed
• Check if tsconfig.json exists; if not, you'll need to create one from scratch
• Verify Node.js version supports TypeScript (v12+) with node --version
• Review your project structure with find . -name "*.js" | head -20 to understand scope

Steps

1. Install TypeScript and type definitions with npm install --save-dev typescript @types/node (add other @types/* packages for your frameworks)
2. Generate a base tsconfig.json with npx tsc --init and set "strict": true, "resolveJsonModule": true, and "skipLibCheck": true
3. Rename entry files from .js to .ts one at a time, starting with files that have fewest dependencies
4. Add explicit return types to all function declarations: function getName(): string { return "John"; }
5. Replace module.exports and require() with ES6 export and import statements
6. Add type annotations to function parameters: function add(a: number, b: number): number
7. Create .d.ts files for untyped third-party packages or use declare module statements
8. Run npx tsc --noEmit frequently to catch type errors without compiling
9. Update package.json scripts section to add "build": "tsc" and adjust start scripts to use compiled .js output
10. Configure your bundler (Webpack, Vite, esbuild) to handle .ts files with appropriate loaders

Code

// Step 1: Create tsconfig.json base configuration
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

// Step 2: Migrate a sample JavaScript file
// Before (index.js):
// module.exports = {
//   greet: (name) => `Hello, ${name}!`,
//   add: (a, b) => a + b
// };

// After (index.ts):
export function greet(name: string): string {
  return

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change