fork-ts-checker-webpack-plugin

fork-ts-checker-webpack-plugin offloads TypeScript type checking to a forked child process, decoupling slow full-program type analysis from webpack’s own compilation pipeline. Instead of blocking every rebuild on tsc-level checks, the plugin hands type checking to a background worker communicating over a lightweight RPC layer built on Node’s IPC channel, and reports diagnostics back to webpack asynchronously once they’re ready.

It is designed to sit alongside a transpile-only loader (typically ts-loader with transpileOnly: true or babel-loader), so webpack emits JavaScript immediately while the checker validates types on its own schedule. This split is what lets teams keep using strict TypeScript project references, incremental builds, and .tsbuildinfo caching without paying their cost on every save during development.

What You Get

• A ForkTsCheckerWebpackPlugin class that taps into webpack’s compiler hooks (afterEnvironment, run/watchRun, done) to start, feed, and stop a background type-checking worker
• Support for TypeScript project references and incremental/--build mode, including write-dts, write-tsbuildinfo, and write-references output modes
• Configurable issue filtering (include/exclude) that matches on severity, error code, or file glob before issues ever reach webpack’s error/warning output
• Pluggable diagnostic formatters (basic, codeframe, or a custom function) for how type errors are rendered in the terminal
• async mode that reports issues after compilation finishes instead of blocking the watch/rebuild cycle, plus webpack-dev-server integration for overlay/logging
• Cosmiconfig-based configuration, so options can live in package.json, .fork-ts-checkerrc, or fork-ts-checker.config.js instead of only the plugin constructor

Common Use Cases

• Pairing with ts-loader in transpileOnly mode so webpack emits JS immediately while this plugin catches type errors in parallel
• Keeping large monorepos with TypeScript project references fast to rebuild by running --build-equivalent checking off the main thread
• Surfacing type errors in the webpack-dev-server overlay during local development without adding type-check latency to hot reloads
• Enforcing selective type-error policies in CI/dev by including or excluding specific files, error codes, or severities from failing a build

Under The Hood

Architecture The plugin’s apply(compiler) method in src/plugin.ts wires a small set of single-purpose hook modules (src/hooks/tap-after-environment-to-patch-watching.ts, tap-start-to-run-workers.ts, tap-after-compile-to-add-dependencies.ts, tap-stop-to-terminate-workers.ts, tap-error-to-log-message.ts) into webpack’s compiler lifecycle, keeping each concern (patching watch mode, spawning workers, reporting dependencies, cleanup, error logging) in its own file rather than one monolithic apply. Type checking itself never runs in-process: src/rpc/rpc-worker.ts forks a child process per worker (get-issues-worker.ts, get-dependencies-worker.ts under src/typescript/worker), passing config through an env var and a custom wrapRpc/exposeRpc protocol built on Node’s IPC channel with advanced serialization, so a plugin instance can restart or terminate a checker process independently of webpack’s own compilation.

Tech Stack Written in TypeScript targeting webpack 5 and TypeScript >3.6 as peer dependencies, with cosmiconfig for layered configuration discovery (constructor options merged via deepmerge over package.json/.fork-ts-checkerrc/fork-ts-checker.config.js), schema-utils validating options against a JSON Schema (plugin-options.json), chokidar for filesystem watching, minimatch for glob-based issue include/exclude filters, and semver for version comparisons; the package is built with tsc directly (no bundler), tested with jest/ts-jest, and released via semantic-release from a Yarn Berry (v4) workspace.

Code Quality The repo runs both a unit suite (test/unit, covering RPC wrapping, issue matching, formatters, path utilities) and a full end-to-end suite (test/e2e, driving real webpack builds against fixture projects via npm pack), with eslint (typescript-eslint + prettier) enforced through husky/lint-staged pre-commit hooks and commitlint gating conventional-commit messages. Public types (RpcMethod, IssueFilter, ForkTsCheckerWebpackPluginOptions) are explicit and exported, and CI runs the full build+test+lint pipeline on every push.

API Design The public surface is a single default-exported class matching webpack’s own plugin convention (new ForkTsCheckerWebpackPlugin(options) + .apply(compiler)), so integration requires no new mental model beyond “add it to the plugins array.” Configuration is grouped into a small number of nested option objects (typescript, issue, formatter, logger, devServer) with sensible defaults, and the cosmiconfig support means teams can keep plugin config out of webpack.config.js entirely if they prefer a dedicated config file.