Loading lesson path
Concept visual
Migrating from JavaScript to TypeScript can significantly improve your codebase's maintainability and developer experience. This guide will walk you through the process step by step.
Identify the size and complexity of your codebase
Check for any existing type definitions (.d.ts files)
Ensure you have a clean git repository or equivalent:
Formula
# Create a new branch for the migration git checkout - b typescript - migration# Commit your current state git add .
Formula
git commit - m "Pre - TypeScript migration state"Formula
# Install TypeScript as a dev dependency npm install -- save - dev typescript @types/nodeCreate tsconfig.json Create a basic tsconfig.json to start with:
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}Note
Adjust the target based on your minimum supported environments.
Migrate one file at a time while keeping the rest as JavaScript.
{
"compilerOptions": {
"allowJs": true,
"checkJs": true
}
}Large codebases, minimal disruption
Rename all.js files to.ts and fix errors. # Rename all JS files to TS
find src -name "*.js" -exec sh -c 'mv "$0" "${0%.js}.ts"' {} \;Small to medium projects, greenfield projects
For large projects, we strongly recommend the gradual migration approach to minimize disruption and make the process more manageable.
Create a basic tsconfig.json with these recommended settings:
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"outDir": "./dist",
"rootDir": "./src",
"allowJs": true,
"checkJs": true,
"noEmit": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}Formula
// @ts - check to the top of your JavaScript files to enable type checking:
// @ts - check/** @type {string} */
const name = 'John';Formula
// TypeScript will catch this error name = 42; // Error: Type '42' is not assignable to type 'string'Note
You can disable type checking for specific lines using
Formula
// @ts - ignore.Rename Files to .ts
Formula
Start with non - critical files and rename them from.js to.tsFormula
# Rename a single file mv src/utils/helpers.js src/utils/helpers.ts# Or rename all files in a directory (use with caution)
find src/utils -name "*.js" -exec sh -c 'mv "$0" "${0%.js}.ts"' {} \;Gradually add type annotations to your code:
// Before function add(a, b) {
return a + b;
}
// After function add(a: number, b: number): number {
return a + b;
}
// With interface interface User {
id: number;
name: string;
email?: string;
}
function getUser(id: number): User {
return { id, name: 'John Doe' };
}Modify your package.json to include TypeScript compilation:
{
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
"test": "jest"
}
}Note
Make sure to update your test configuration to work with TypeScript files.
Formula
Automated tool for migrating JavaScript to TypeScript npx ts - migrate - full .Converts JavaScript to TypeScript with type safety npx typestat