TypeScript's progressive adoption strategy for front-end projects

The strategy of incrementally adopting TypeScript in front-end projects usually includes:

Introducing TypeScript

If we have a simple JavaScript module utils.js, which contains a function for calculating the sum of two numbers:

// utils.js
export function add(a, b) {
    return a + b;
}

First, we change the file extension to .ts and start adding type annotations step by step:

// utils.ts
export function add(a: number, b: number): number {
    return a + b;
}

Setting up tsconfig.json

Create a tsconfig.json in the project root directory to configure the TypeScript compiler:

{
// Specify the target ECMAScript version for compilation
"target": "es6",

// Specify the module system
"module": "esnext",

// Output directory, where the compiled files are stored
"outDir": "./dist",

// Whether to include source map files for debugging
"sourceMap": true,

// Enable strict type checking options
"strict": true,

// Allow default imports from modules that do not set default exports
"esModuleInterop": true,

// Ignore type checking for libraries
"skipLibCheck": true,

// Ensure consistent case for file names
"forceConsistentCasingInFileNames": true,

// Which files to include for compilation
"include": [
    "src/**/*.ts",
    "src/**/*.tsx" // If TypeScript's JSX is used in the project
],

// Which files or directories are excluded from compilation
"exclude": [
    "node_modules",
    "**/*.spec.ts" // Exclude test files
]
}

Advanced Configuration Items

paths: Used for path alias configuration to facilitate path management when importing modules.

"paths": {
    "@components/*": ["src/components/*"]
}

baseUrl: Set the base directory of the project. When used with paths, it can provide a more concise import path.

    "baseUrl": "./src"

resolveJsonModule: Allows direct import of JSON files.

    "resolveJsonModule": true

lib: Specifies the library file collection used in the project, such as ECMAScript, DOM, etc.

    "lib": ["es6", "dom"]

jsx: If the project uses JSX syntax, this option needs to be set.

    "jsx": "react-jsx"

Inherited configuration

If your project structure is complex, you may need different configurations in different directories. You can use the extends property to inherit a basic tsconfig.json:

// tsconfig.app.json in a subdirectory
{
    "extends": "../tsconfig.json",
    "compilerOptions": {
    // You can override or add application-specific compilation options here
    },
    // You can add or modify include and exclude here
}

Integrate TypeScript into the build process

Integrating TypeScript into the build process usually involves adjusting the configuration of the build tool (such as Webpack, Rollup, or Parcel). And adding TypeScript processing rules in the configuration file.

npm install --save-dev typescript ts-loader webpack webpack-cli

webpack.config.js配置文件

const path = require('path');

module.exports = {
  entry: './src/index.ts', // Your entry file, usually index.ts
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'], // Add .ts and .tsx extensions
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/, // Exclude the node_modules directory
      },
    ],
  },
  devtool: 'source-map', // Generate source map for easy debugging during development
};

In tsconfig.json , make sure you have configured the correct outDir to match the output directory of Webpack :

{
  // ...
  "outDir": "./dist",
  // ...
}

Now you can start the build process by running the following command from the command line:

npx webpack

This will compile the TypeScript source code into JavaScript using Webpack and ts-loader and output it to the dist directory.

If you are using npm scripts, you can add a build script to package.json:

{
  "scripts": {
    "build": "webpack"
  }
}

Then run the build via npm run build.

Using type definitions

If you use third-party libraries in your project, make sure to install the corresponding type definition packages, such as @types/lodash. For libraries without official type definitions, you can try the definitions provided by the community or write your own declaration files.

1. Install type definition packages:

Most popular libraries have corresponding type definition packages, usually located in the @types namespace. For example, if you use lodash in your project, you can run the following command to install its type definitions:

npm install --save-dev @types/lodash

Or use Yarn:

yarn add --dev @types/lodash

2. Automatic type inference

After installing type definitions, the TypeScript compiler will automatically recognize and use these type definitions. You don't need to explicitly import them in your code, just reference the library normally in your project.

3. Custom type definitions

If you use a library that doesn't have official type definitions, or the official type definitions are incomplete, you can write your own type declaration file (.d.ts). Typically, this file should be placed in the same location as the library's JavaScript file, or in the types or @types directory.

For example, suppose there is a library called customLib, and its main file is customLib.js. You can create a customLib.d.ts file to declare its types:

declare module 'customLib' {
    export function doSomething(data: string): void;
    export interface CustomInterface {
     property: number;
    }
}

Then in your code, TypeScript will recognize and use these types.

4. Community type definitions

Sometimes, the community will provide unofficial type definitions. You can find it in the DefinitelyTyped repository (https://github.com/DefinitelyTyped/DefinitelyTyped), or search for @types/library-name on GitHub.

5. Limitations of type definitions

While type definitions are helpful for improving code quality, not all libraries provide complete type definitions, or they may not fully match the actual behavior of the library. In this case, you may need to use the any type or // @ts-ignore comment in your code to skip specific type checks.

IDE integration

Make sure your IDE (such as VSCode) has the TypeScript plugin installed to get code completion, type checking, and other features.

Gradually migrate other modules

Over time, you can gradually convert other JavaScript modules to TypeScript. For example, suppose there is an app.js, which can be similarly converted to app.ts and add type annotations.

• Rename app.js to app.ts. This step marks that the module has officially entered the TypeScript environment.

• Open app.ts and start adding type annotations to variables, function parameters, return values, etc. This helps the TypeScript compiler to perform type checking and reduce potential type errors.
  

// JavaScript
function fetchData(url) {
    return fetch(url).then(response => response.json());
}

// Convert to TypeScript
async function fetchData(url: string): Promise<any> {
const response = await fetch(url);
return response.json();
}

• For complex data structures, consider using interfaces (interface) or type aliases (type alias) to define types to improve code readability and maintainability.

interface User {
    id: number;
    name: string;
    email: string;
}

function getUser(): User {
// ...
}

Strengthen type checking

After your team gets used to TypeScript, you can gradually enable stricter type checking options in tsconfig.json, such as strictNullChecks.