Fork TS Checker Webpack Plugin

9.1.0 · active · verified Sun Apr 19

The `fork-ts-checker-webpack-plugin` is a Webpack plugin designed to significantly improve build performance in TypeScript projects by offloading the TypeScript type checking process to a separate worker process. This allows `ts-loader` or `babel-loader` to operate in `transpileOnly` mode, focusing solely on transpilation without blocking the main Webpack compilation thread for type checks. The current stable version is 9.1.0, released on April 3, 2025. The project has a moderately active release cadence, issuing several patches and minor versions annually, with major versions arriving less frequently but introducing breaking changes like Node.js or TypeScript version bumps. Key differentiators include its support for modern TypeScript features such as project references and incremental builds, and its ability to display well-formatted error messages with code frames directly within the Webpack output. It's an essential tool for maintaining fast build times in large TypeScript-based Webpack applications.

Common errors

```
Error: Worker caught an error: Unhandled error in worker.
```
cause The plugin's worker process crashed due to an unhandled internal error, often related to an unexpected TypeScript or system state.

fix This specific error was fixed in `v9.0.1`. Upgrade `fork-ts-checker-webpack-plugin` to version 9.0.1 or newer. If the problem persists, check your TypeScript configuration for any unusual setups or corrupted files.
```
Type checking occurs in node_modules on Windows, leading to unexpected errors or slow performance.
```
cause An issue in older versions of the plugin on Windows where `node_modules` directories were not correctly ignored by the type checker.

fix Upgrade `fork-ts-checker-webpack-plugin` to version 8.0.0 or newer. This version includes a fix for ignoring `node_modules` on Windows.
```
Error: 'performance.now()' is not compatible with TypeScript 5.
```
cause Compatibility issues with the plugin's performance API when used with TypeScript 5.

fix Upgrade `fork-ts-checker-webpack-plugin` to version 6.5.3 or newer. This version provides compatibility with TypeScript 5's performance API.
```
No TypeScript errors are displayed in Webpack output, even though `tsc` reports errors.
```
cause The plugin might not be correctly configured, or `ts-loader` is running in `transpileOnly: false` mode, causing it to block compilation on errors before the plugin can report them.

fix Ensure `fork-ts-checker-webpack-plugin` is correctly instantiated in your Webpack plugins array. Verify `ts-loader` has `options: { transpileOnly: true }` enabled to delegate type checking to the plugin.

Warnings

breaking Version 9.0.0 of `fork-ts-checker-webpack-plugin` dropped support for Node.js v12. Users must upgrade to Node.js v14.21.3 or newer.
Fix: Upgrade your Node.js environment to version 14.21.3 or higher. If unable to upgrade Node.js, downgrade the plugin to version 8.x.
breaking Version 8.0.0 removed built-in support for Vue.js SFCs (Single File Components). Projects relying on Vue.js type checking should use version 6.x of the plugin or integrate alternative solutions.
Fix: For Vue.js support, downgrade to `fork-ts-checker-webpack-plugin@6` or implement a custom type checking solution for Vue SFCs.
gotcha If using `ts-loader` versions older than 9.3.0, it is essential to set `transpileOnly: true` in its options. Failure to do so will cause `ts-loader` to perform type checking itself, negating the performance benefits of this plugin.
Fix: Add `options: { transpileOnly: true }` to your `ts-loader` rule in `webpack.config.js`.
gotcha The `watchOptions.ignored: /node_modules/` configuration in Webpack can cause issues in monorepos or projects with linked packages, as changes in `node_modules` of linked packages might not trigger recompilations.
Fix: Adjust the `watchOptions.ignored` pattern to specifically include only external `node_modules` or remove it if using a monorepo setup with symlinked packages.
breaking Older versions of Webpack (v4) or TypeScript (2.1-2.6.2 or 2.7-3.5.3) require specific older versions of `fork-ts-checker-webpack-plugin`. Consult the README for compatibility matrices.
Fix: Ensure your `fork-ts-checker-webpack-plugin` version aligns with your Webpack and TypeScript versions. For Webpack 4, use plugin version 6.x. For TypeScript 2.1-2.6.2, use plugin version 4.x. For TypeScript 2.7-3.5.3, use plugin version 6.x.

Install

npm install fork-ts-checker-webpack-plugin npm
yarn add fork-ts-checker-webpack-plugin yarn
pnpm add fork-ts-checker-webpack-plugin pnpm

Imports

ForkTsCheckerWebpackPlugin
wrong:
```
import { ForkTsCheckerWebpackPlugin } from 'fork-ts-checker-webpack-plugin';
```
correct:
```
import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
```
The plugin is a default export. While Webpack configurations often use CommonJS `require()`, modern JavaScript modules use the default import syntax.
ForkTsCheckerWebpackPlugin (CommonJS)
```
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
```
This is the most common way to import the plugin in `webpack.config.js` files, which are typically CommonJS modules.
ForkTsCheckerWebpackPlugin.Options
```
import type { ForkTsCheckerWebpackPluginOptions } from 'fork-ts-checker-webpack-plugin';
```
Import the type definition for plugin options for type-safe configuration in TypeScript.

Quickstart

This quickstart demonstrates how to integrate `fork-ts-checker-webpack-plugin` with `ts-loader` in a minimal Webpack configuration. It highlights the use of `transpileOnly: true` on `ts-loader` to offload type checking to the plugin's separate process, thereby speeding up build times.

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  context: __dirname,
  entry: './src/index.ts',
  resolve: {
    extensions: [".ts", ".tsx", ".js"]
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'ts-loader',
        options: {
          transpileOnly: true // Crucial for performance with this plugin
        }
      }
    ]
  },
  plugins: [new ForkTsCheckerWebpackPlugin()],
  watchOptions: {
    ignored: /node_modules/ // Adjust for monorepos
  }
};

view raw JSON →