Install TypeScript and configure tsconfig.json, enable allowJs to support mixed JavaScript and TypeScript files; 2. Start with orphan modules such as tool functions, gradually rename the .js file to .ts and fix type errors. You can first use JSDoc to improve type inference; 3. Gradually enable strict check rules in strict mode, solve problems such as noImplicitAny and strictNullChecks one by one to avoid abuse of @ts-ignore; 4. Install the @types package for third-party libraries, create declaration files in the types directory when types are missing and configure typeRoots; 5. Integrate tsc into the construction process, set up type-check scripts and run them in CI to prevent type degradation; 6. Add interface or type definition during refactoring, replace any with specific types, and maintain incremental improvements; 7. The team introduced ESLint and TypeScript integration, configuration editor support, and shared type definition mode. The key to migration is to gradually advance rather than rewrite, and to achieve type safety through small-step iteration. Even some adoption can effectively reduce production environment bugs. The ultimate goal is to continuously improve type coverage without interrupting existing functions.

Migrating a JavaScript project to TypeScript isn't about rewriting everything overnight—it's about incrementally adding type safety while keeping your code functional. Here's how to do it step by step, without breaking your app or team workflow.

1. Set Up TypeScript in Your Project

Start by installing TypeScript and setting up the configuration file.

 npm install typescript --save-dev
npm install @types/node --save-dev # Common types, adjust as needed

Create a tsconfig.json file to define how TypeScript should behave:

 {
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "allowJs": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Key options:

• "allowJs": true – lets you keep .js files while gradually adding .ts .
• "strict": true – enables strict type checking (recommended for new conversions).
• "outDir" and "rootDir" – keep your compiled output organized.

You can generate this file interactively:

 npx tsc --init

2. Start with Smaller, Isolated Files

Don't try to convert your entire codebase at once. Begin with:

• Utility functions
• Helper modules
• Pure components (in React/Vue apps)

Rename a .js file to .ts (or .tsx if using React with JSX), then run:

 npx tsc --noEmit

This checks types without generating output. Fix any errors that appear.

? Pro tip: Use JSDoc comments in .js files first to get better type inference. TypeScript can understand types like:

 /**
 * @param {string} name
 * @returns {number}
 */
function getNameLength(name) {
  return name.length;
}

This helps during the transition and improves autocomplete.

3. Gradually Enforce Type Safety

Once TypeScript is running, increase the strictness over time.

Update tsconfig.json to catch more issues:

 "noImplicitAny": true,
"strictNullChecks": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true

Fix one rule at a time. For example:

• Start with noImplicitAny → add types where they're missing.
• Then enable strictNullChecks → handle null / undefined cases.

Use // @ts-ignore sparingly—and always add a comment explaining why:

 // @ts-ignore: Temporary ignore until API response is typed
const data = response.data.users;

Better yet, use // @ts-expect-error if you plan to fix it later.

4. Handle Third-Party Libraries

Many npm packages have built-in TypeScript support or community-maintained types.

Install types when available:

 npm install @types/react @types/express @types/lodash --save-dev

If types don't exist:

• Create a shim in types/ folder:

   // types/my-library.d.ts
  declare module 'my-library' {
    const value: any;
    export default value;
  }

• Reference it in tsconfig.json :

   "typeRoots": ["node_modules/@types", "types"]

5. Integrate with Your Build Tool

Update your build scripts to run TypeScript.

For example, in package.json :

 "scripts": {
  "build": "tsc",
  "dev": "tsc --watch"
}

If you're using Babel (eg, in Create React App), you can let Babel handle TypeScript (but you still need tsc --noEmit for type checking in CI).

Add a type-checking script:

 "scripts": {
  "type-check": "tsc --noEmit",
  "type-check:watch": "tsc --noEmit --watch"
}

Run it in your CI pipeline to prevent type regressions.

6. Refactor Step by Step

As you convert files:

• Rename .js → .ts
• Add interfaces for object shapes
• Replace any with specific types when possible

Example:

 // Before (in .js with JSDoc or implicit any)
function createUser(user) {
  return { id: 1, ...user };
}

// After
interface User {
  name: string;
  email: string;
}

function createUser(user: User): User & { id: number } {
  return { id: 1, ...user };
}

Use interface or type based on preference:

• interface is extendable and good for object shapes.
• type is more flexible (unions, primitives, etc.).

7. Train Your Team and Update Tooling

• Add TypeScript linting with ESLint:

   npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

• Configure .eslintrc to support TypeScript syntax and best practices.
• Set up editor support (VS Code works great out of the box).
• Share common patterns in your team (eg, how to type React props, Redux actions, etc.).

---

Final Thoughts

TypeScript migration is a journey—not a one-time event. The key is:

• Start small
• Keep the app running
• Incrementally improve type coverage
• Use tooling to catch errors early

You don't need 100% TypeScript to benefit from 20% adoption. Even partial typing catches bugs before they reach production.

Basically, just get started—and keep moving forward.

The above is the detailed content of Migrating a JavaScript Project to TypeScript: A Step-by-Step Guide. For more information, please follow other related articles on the PHP Chinese website!