Fork TS Checker Async Overlay Webpack Plugin

0.4.0 verified Sat Apr 25 auth: no javascript

A webpack plugin that connects fork-ts-checker-webpack-plugin (with async: true) to the error overlay of webpack-dev-server. Version 0.4.0 is the latest stable release. The plugin addresses the limitation that type checking errors from fork-ts-checker-webpack-plugin are not shown in the dev server overlay when running asynchronously (async: true). It works by re-firing the webpack-dev-server's done hook after type checking completes, but only if there are errors, to avoid unnecessary page reloads. It requires fork-ts-checker-webpack-plugin ^4.1.6 as a peer dependency and is intended for use with ts-loader's transpileOnly option. Key differentiator: allows fast incremental builds (async: true) while still showing type errors in overlay, avoiding the need to set async: false which slows down builds.

Common errors

error Type errors not showing in overlay even though fork-ts-checker-webpack-plugin reports them ↓

cause Missing devServer.overlay: true or devServer.inline: true, or missing .plugins() call.

fix

Ensure devServer config has overlay: true and inline: true, and call .plugins() on the plugin instance.

error Cannot find module 'fork-ts-checker-async-overlay-webpack-plugin' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install fork-ts-checker-async-overlay-webpack-plugin --save-dev'.

error TypeError: ForkTsCheckerAsyncOverlayWebpackPlugin is not a constructor ↓

cause Using ES module import syntax instead of require.

fix

Use require() instead of import: const ForkTsCheckerAsyncOverlayWebpackPlugin = require('fork-ts-checker-async-overlay-webpack-plugin');

Warnings

gotcha Only errors (not warnings) are shown in overlay. ↓

fix Use fork-ts-checker-webpack-plugin's built-in warning reporting or no overlay for warnings.

gotcha The plugin requires devServer.overlay to be true and devServer.inline to be true. ↓

fix Set devServer: { overlay: true, inline: true } in webpack config.

gotcha The plugin only re-fires the done hook if there are errors; otherwise the overlay is not updated. ↓

fix Expected behavior; no workaround.

breaking Major version 0.x: API may change without notice. Peer dependency on fork-ts-checker-webpack-plugin ^4.1.6 may not be compatible with newer versions. ↓

fix Pin fork-ts-checker-webpack-plugin to ^4.1.6 and monitor for updates.

Install

npm install fork-ts-checker-async-overlay-webpack-plugin

yarn add fork-ts-checker-async-overlay-webpack-plugin

pnpm add fork-ts-checker-async-overlay-webpack-plugin

Imports

default

wrong

import ForkTsCheckerAsyncOverlayWebpackPlugin from 'fork-ts-checker-async-overlay-webpack-plugin'

correct

const ForkTsCheckerAsyncOverlayWebpackPlugin = require('fork-ts-checker-async-overlay-webpack-plugin')

CJS only; no default ES module export available.

ForkTsCheckerAsyncOverlayWebpackPlugin

const ForkTsCheckerAsyncOverlayWebpackPlugin = require('fork-ts-checker-async-overlay-webpack-plugin')

Use the require form. The package does not export named symbols.

Quickstart

Configures webpack with ts-loader (transpileOnly), fork-ts-checker-webpack-plugin, and this plugin to show type errors in dev server overlay.

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: 'ts-loader',
          options: { transpileOnly: true }
        },
        exclude: /node_modules/
      }
    ]
  },
  plugins: [].concat(
    new ForkTsCheckerAsyncOverlayWebpackPlugin({
      checkerPlugin: new ForkTsCheckerWebpackPlugin()
    }).plugins()
  ),
  devServer: {
    overlay: true,
    inline: true
  }
};