Fork TS Checker Webpack Plugin

Webpack plugin that runs TypeScript type checker on a separate process.

Features

Speeds up TypeScript type checking and ESLint linting (by moving each to a separate process) 🏎
Supports modern TypeScript features like project references and incremental mode ✨
Supports Vue Single File Component ✅
Displays nice error messages with the code frame formatter 🌈

Installation

This plugin requires minimum Node.js 10, Webpack 4, TypeScript 2.7 and optionally ESLint 6

If you depend on Webpack 2, Webpack 3, or TSLint 4, please use version 3 of the plugin.
If you depend on TypeScript >= 2.1 and < 2.7 or you can't update to Node 10, please use version 4 of the plugin.

# with npm
npm install --save-dev fork-ts-checker-webpack-plugin

# with yarn
yarn add --dev fork-ts-checker-webpack-plugin

The minimal webpack config (with ts-loader)

// webpack.config.js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  context: __dirname, // to automatically find tsconfig.json
  entry: './src/index.ts',
  resolve: {
    extensions: [".ts", ".tsx", ".js"],
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'ts-loader',
        exclude: /node_modules/,
        options: {
          // disable type checker - we will use it in fork plugin
          transpileOnly: true
        }
      }
    ]
  },
  plugins: [new ForkTsCheckerWebpackPlugin()]
};

If you are using TypeScript >= 2.8.0, it's recommended to set "importsNotUsedAsValues": "preserve" compiler option in the tsconfig.json. Here is an explanation.

You can find examples how to configure it with babel-loader, ts-loader, eslint and Visual Studio Code in the examples directory.

Modules resolution

It's very important to be aware that this plugin uses TypeScript's, not webpack's modules resolution. It means that you have to setup tsconfig.json correctly. For example if you set files: ['./src/index.ts'] in tsconfig.json, this plugin will check only index.ts for errors.

It's because of the performance - with TypeScript's module resolution we don't have to wait for webpack to compile files.

To debug TypeScript's modules resolution, you can use tsc --traceResolution command.

ESLint

If you'd like to use ESLint with the plugin, ensure you have the relevant dependencies installed:

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

# with yarn
yarn add --dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Then set up ESLint in the plugin. This is the minimal configuration:

// webpack.config.js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  // ...the webpack configuration
  plugins: [
    new ForkTsCheckerWebpackPlugin({
      eslint: {
        files: './src/**/*' // required - same as command `eslint ./src/**/* --ext .ts,.tsx,.js,.jsx`
      }
    })
  ]
};

You should also have an ESLint configuration file in your root project directory. Here is a sample .eslintrc.js configuration for a TypeScript project:

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2018,
    sourceType: 'module',
  },
  extends: [
    'plugin:@typescript-eslint/recommended'
  ],
  rules: {
    // place to specify ESLint rules - can be used to overwrite rules specified from the extended configs
    // e.g. "@typescript-eslint/explicit-function-return-type": "off",
  }
};

There's a good explanation on setting up TypeScript ESLint support by Robert Cooper.

Options

This plugin uses cosmiconfig. This means that besides the plugin constructor, you can place your configuration in the:

"fork-ts-checker" field in the package.json
.fork-ts-checkerrc file in JSON or YAML format
fork-ts-checker.config.js file exporting a JS object

Options passed to the plugin constructor will overwrite options from the cosmiconfig (using deepmerge).

Name	Type	Default value	Description
`async`	`boolean`	`compiler.options.mode === 'development'`	If `true`, reports issues after webpack's compilation is done. Thanks to that it doesn't block the compilation. Used only in the `watch` mode.
`typescript`	`object` or `boolean`	`true`	If a `boolean`, it enables/disables TypeScript checker. If an `object`, see TypeScript options.
`eslint`	`object`	`undefined`	If `undefined`, it disables ESLint linter. If an `object`, see ESLint options.
`issue`	`object`	`{}`	See Issues options.
`formatter`	`string` or `object`	`codeframe`	Available formatters are `basic` and `codeframe`. To configure `codeframe` formatter, pass object: `{ type: 'codeframe', options: { <coderame options> } }`.
`logger`	`object`	`{ infastructure: 'silent', issues: 'console' }`	Available loggers are `silent`, `console`, and `webpack-infrastructure`. Infrastructure logger prints additional information, issue logger prints `issues` in the `async` mode.

TypeScript options

Options for the TypeScript checker (typescript option object).

Name	Type	Default value	Description
`enabled`	`boolean`	`true`	If `true`, it enables TypeScript checker.
`memoryLimit`	`number`	`2048`	Memory limit for the checker process in MB. If the process exits with the allocation failed error, try to increase this number.
`tsconfig`	`string`	`'tsconfig.json'`	Path to the `tsconfig.json` file (path relative to the `compiler.options.context` or absolute path)
`context`	`string`	`dirname(configuration.tsconfig)`	The base path for finding files specified in the `tsconfig.json`. Same as the `context` option from the ts-loader. Useful if you want to keep your `tsconfig.json` in an external package. Keep in mind that not having a `tsconfig.json` in your project root can cause different behaviour between `fork-ts-checker-webpack-plugin` and `tsc`. When using editors like `VS Code` it is advised to add a `tsconfig.json` file to the root of the project and extend the config file referenced in option `tsconfig`.
`build`	`boolean`	`false`	The equivalent of the `--build` flag for the `tsc` command. To enable `incremental` mode, set it in the `tsconfig.json` file.
`mode`	`'readonly'` or `'write-tsbuildinfo'` or `'write-references'`	`'readonly'`	If you use the `babel-loader`, it's recommended to use `write-references` mode to improve initial compilation time. If you use `ts-loader`, it's recommended to use `readonly` mode to not overwrite filed emitted by `ts-loader`.
`compilerOptions`	`object`	`{ skipLibCheck: true, skipDefaultLibCheck: true }`	These options will overwrite compiler options from the `tsconfig.json` file.
`diagnosticsOptions`	`object`	`{ syntactic: false, semantic: true, declaration: false, global: false }`	Settings to select which diagnostics do we want to perform.
`extensions`	`object`	`{}`	See TypeScript extensions options.

TypeScript extensions options

Options for the TypeScript checker extensions (typescript.extensions option object).

Name	Type	Default value	Description
`vue`	`object` or `boolean`	`false`	If `true`, it enables Vue Single File Component support.
`vue.enabled`	`boolean`	`false`	Same as the `vue` option
`vue.compiler`	`string`	`'vue-template-compiler'`	The package name of the compiler that will be used to parse `.vue` files. You can use `'nativescript-vue-template-compiler'` if you use nativescript-vue

ESLint options

Options for the ESLint linter (eslint option object).

Name	Type	Default value	Description
`enabled`	`boolean`	`false`	If `true`, it enables ESLint linter.
`files`	`string` or `string[]`	This value is required	One or more glob patterns to the files that should be linted. Works the same as the `eslint` command.
`memoryLimit`	`number`	`2048`	Memory limit for the linter process in MB. If the process exits with the allocation failed error, try to increase this number.
`options`	`object`	`{}`	Options that can be used to initialize ESLint.

Issues options

Options for the issues filtering (issues option object).

Name	Type	Default value	Description
`include`	`object` or `function` or `array`	`undefined`	If `object`, defines issue properties that should be matched. If `function`, acts as a predicate where `issue` is an argument.
`exclude`	`object` or `function` or `array`	`undefined`	Same as `include` but issues that match this predicate will be excluded.

Vue.js

⚠️ There are additional constraints regarding Vue.js Single File Component support: ⚠️

It requires TypeScript >= 3.8.0 and "importsNotUsedAsValues": "preserve" option in the tsconfig.json (it's a limitation of the transpileOnly mode from ts-loader)
It doesn't work with the build mode (project references)

To enable Vue.js support, follow these steps:

<summary>Expand Vue.js set up instruction</summary>

Ensure you have all required packages installed:

# with npm
npm install --save vue vue-class-component
npm install --save-dev vue-loader ts-loader css-loader vue-template-compiler 

# with yarn
yarn add vue vue-class-component
yarn add --dev vue-loader ts-loader css-loader vue-template-compiler

Add tsconfig.json configuration:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "jsx": "preserve",
    "target": "ES5",
    "lib": ["ES6", "DOM"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "~/*": ["src/*"]
    },
    "sourceMap": true,
    "importsNotUsedAsValues": "preserve"
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

Add webpack.config.js configuration:

const path = require('path');
const VueLoaderPlugin = require('vue-loader/lib/plugin');
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  entry: './src/index.ts',
  output: {
    filename: 'index.js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      },
      {
        test: /\.ts$/,
        loader: 'ts-loader',
        exclude: /node_modules/,
        options: {
          appendTsSuffixTo: [/\.vue$/],
          transpileOnly: true
        }
      },
      {
        test: /\.css$/,
        loader: 'css-loader'
      },
    ],
  },
  resolve: {
    extensions: ['.ts', '.js', '.vue', '.json'],
    alias: {
      '@': path.resolve(__dirname, './src'),
      '~': path.resolve(__dirname, './src'),
    }
  },
  plugins: [
    new VueLoaderPlugin(),
    new ForkTsCheckerWebpackPlugin({
      typescript: {
        extensions: {
          vue: true
        }
      }
    })
  ]
};

Add src/types/vue.d.ts file to shim .vue modules:

declare module "*.vue" {
  import Vue from "vue";
  export default Vue;
}

If you are working in VSCode, you can get the Vetur extension to complete the developer workflow.

Type-Only modules watching

At present there is an issue with the transpileOnly mode regarding the triggering of type-checking when a change is made in a source file that will not emit js. If you have a file that contains only interfaces and/or types then, by default, changes to it will not trigger the type checker whilst in watch mode.

If you use TypeScript >=3.8.0, you can fix it by passing "importsNotUsedAsValues": "preserve" option to the compiler options in the tsconfig.json.

Plugin hooks

This plugin provides some custom webpack hooks:

Hook key	Type	Params	Description
`start`	`AsyncSeriesWaterfallHook`	`change, compilation`	Starts issues checking for a compilation. It's an async waterfall hook, so you can modify the list of changed and removed files or delay the start of the service.
`waiting`	`SyncHook`	`compilation`	Waiting for the issues checking.
`canceled`	`SyncHook`	`compilation`	Issues checking for the compilation has been canceled.
`error`	`SyncHook`	`compilation`	An error occurred during issues checking.
`issues`	`SyncWaterfallHook`	`issues, compilation`	Issues have been received and will be reported. It's a waterfall hook, so you can modify the list of received issues.

To access plugin hooks and tap into the event, we need to use the getCompilerHooks static method. When we call this method with a webpack compiler instance, it returns the object with tapable hooks where you can pass in your callbacks.

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

const compiler = webpack({
  // ... webpack config
});

// optionally add the plugin to the compiler
// **don't do this if already added through configuration**
new ForkTsCheckerWebpackPlugin().apply(compiler);

// now get the plugin hooks from compiler
const hooks = ForkTsCheckerWebpackPlugin.getCompilerHooks(compiler);

// say we want to show some message when plugin is waiting for issues results
hooks.waiting.tap('yourListenerName', () => {
  console.log('waiting for issues');
});

Typings

To use the plugin typings, you have to install @types/webpack. It's not included by default to not collide with your existing typings (@types/webpack imports @types/node). It's an old TypeScript issue, the alternative is to set skipLibCheck: true in the compilerOptions 😉

# with npm
npm install --save-dev @types/webpack

# with yarn
yarn add --dev @types/webpack

Related projects

ts-loader - TypeScript loader for webpack.
babel-loader - Alternative TypeScript loader for webpack.
fork-ts-checker-notifier-webpack-plugin - Notifies about build status using system notifications (similar to the webpack-notifier).

Credits

This plugin was created in Realytics in 2017. Thank you for supporting Open Source.

License

MIT License

Current Tags

7.0.0-alpha.16 ... alpha (3 years ago)
5.0.0-beta.7 ... beta (4 years ago)
9.0.2 ... latest (a year ago)
1.0.0-alpha.10 ... next (6 years ago)
6.5.3 ... release-6.5.x (2 years ago)

222 Versions

9.0.2 ... a year ago
9.0.1 ... a year ago
9.0.0 ... a year ago
8.0.0 ... 2 years ago
6.5.3 ... 2 years ago
7.3.0 ... 2 years ago
7.2.14 ... 2 years ago
7.2.13 ... 2 years ago
7.2.12 ... 2 years ago
7.2.11 ... 3 years ago
7.2.10 ... 3 years ago
7.2.9 ... 3 years ago
7.2.8 ... 3 years ago
6.5.2 ... 3 years ago
7.2.7 ... 3 years ago
7.2.6 ... 3 years ago
7.2.5 ... 3 years ago
7.2.4 ... 3 years ago
6.5.1 ... 3 years ago
7.2.3 ... 3 years ago
7.2.2 ... 3 years ago
7.2.1 ... 3 years ago
7.2.0 ... 3 years ago
7.1.1 ... 3 years ago
7.1.0 ... 3 years ago
7.0.0 ... 3 years ago
7.0.0-alpha.16 ... 3 years ago
7.0.0-alpha.15 ... 3 years ago
7.0.0-alpha.14 ... 3 years ago
7.0.0-alpha.13 ... 3 years ago
7.0.0-alpha.12 ... 3 years ago
7.0.0-alpha.11 ... 3 years ago
6.5.0 ... 3 years ago
6.4.2 ... 3 years ago
6.4.1 ... 3 years ago
7.0.0-alpha.10 ... 3 years ago
7.0.0-alpha.9 ... 3 years ago
6.4.0 ... 3 years ago
6.3.6 ... 3 years ago
6.3.5 ... 3 years ago
6.3.4 ... 3 years ago
6.3.3 ... 3 years ago
7.0.0-alpha.8 ... 3 years ago
7.0.0-alpha.7 ... 3 years ago
6.3.2 ... 3 years ago
7.0.0-alpha.6 ... 3 years ago
7.0.0-alpha.5 ... 3 years ago
7.0.0-alpha.4 ... 3 years ago
6.3.1 ... 3 years ago
6.3.0 ... 3 years ago
6.2.13 ... 3 years ago
6.2.12 ... 3 years ago
6.2.11 ... 3 years ago
6.2.10 ... 3 years ago
6.2.9 ... 4 years ago
6.2.8 ... 4 years ago
7.0.0-alpha.3 ... 4 years ago
6.2.7 ... 4 years ago
7.0.0-alpha.2 ... 4 years ago
6.2.6 ... 4 years ago
6.2.5 ... 4 years ago
6.2.4 ... 4 years ago
6.2.3 ... 4 years ago
6.2.2 ... 4 years ago
6.2.1 ... 4 years ago
6.2.0 ... 4 years ago
7.0.0-alpha.1 ... 4 years ago
6.1.1 ... 4 years ago
6.1.0 ... 4 years ago
6.0.8 ... 4 years ago
6.0.7 ... 4 years ago
6.0.6 ... 4 years ago
6.0.5 ... 4 years ago
6.0.4 ... 4 years ago
6.0.3 ... 4 years ago
6.0.2 ... 4 years ago
6.0.1 ... 4 years ago
6.0.0 ... 4 years ago
6.0.0-alpha.3 ... 4 years ago
5.2.1 ... 4 years ago
6.0.0-alpha.2 ... 4 years ago
6.0.0-alpha.1 ... 4 years ago
5.2.0 ... 4 years ago
5.1.0 ... 4 years ago
5.0.14 ... 4 years ago
5.0.13 ... 4 years ago
5.0.12 ... 4 years ago
5.0.11 ... 4 years ago
5.0.10 ... 4 years ago
5.0.9 ... 4 years ago
5.0.8 ... 4 years ago
5.0.7 ... 4 years ago
5.0.6 ... 4 years ago
5.0.5 ... 4 years ago
5.0.4 ... 4 years ago
5.0.3 ... 4 years ago
5.0.2 ... 4 years ago
5.0.1 ... 4 years ago
5.0.0 ... 4 years ago
5.0.0-beta.7 ... 4 years ago
5.0.0-beta.6 ... 4 years ago
5.0.0-beta.5 ... 4 years ago
5.0.0-beta.4 ... 4 years ago
5.0.0-beta.3 ... 4 years ago
5.0.0-beta.2 ... 4 years ago
5.0.0-alpha.17 ... 4 years ago
5.0.0-beta.1 ... 4 years ago
5.0.0-alpha.16 ... 4 years ago
5.0.0-alpha.15 ... 4 years ago
5.0.0-alpha.14 ... 4 years ago
5.0.0-alpha.13 ... 4 years ago
5.0.0-alpha.12 ... 4 years ago
5.0.0-alpha.11 ... 4 years ago
5.0.0-alpha.10 ... 4 years ago
4.1.6 ... 4 years ago
5.0.0-alpha.9 ... 4 years ago
5.0.0-alpha.8 ... 4 years ago
5.0.0-alpha.7 ... 4 years ago
5.0.0-alpha.6 ... 4 years ago
5.0.0-alpha.5 ... 4 years ago
5.0.0-alpha.4 ... 4 years ago
5.0.0-alpha.3 ... 4 years ago
4.1.5 ... 4 years ago
5.0.0-alpha.2 ... 4 years ago
5.0.0-alpha.1 ... 4 years ago
4.1.4 ... 4 years ago
4.1.3 ... 5 years ago
4.1.2 ... 5 years ago
4.1.1 ... 5 years ago
4.1.0 ... 5 years ago
4.0.5 ... 5 years ago
4.0.4 ... 5 years ago
4.0.3 ... 5 years ago
4.0.2 ... 5 years ago
4.0.1 ... 5 years ago
4.0.0-beta.5 ... 5 years ago
4.0.0-beta.4 ... 5 years ago
4.0.0-beta.3 ... 5 years ago
4.0.0-beta.2 ... 5 years ago
4.0.0-beta.1 ... 5 years ago
3.1.1 ... 5 years ago
3.1.0 ... 5 years ago
3.0.1 ... 5 years ago
3.0.0 ... 5 years ago
2.0.0 ... 5 years ago
1.6.0 ... 5 years ago
1.5.1 ... 5 years ago
1.5.0 ... 5 years ago
1.4.3 ... 5 years ago
1.4.2 ... 5 years ago
1.4.1 ... 5 years ago
1.4.0 ... 5 years ago
1.3.7 ... 5 years ago
1.3.6 ... 5 years ago
1.3.5 ... 5 years ago
1.3.4 ... 5 years ago
1.3.3 ... 5 years ago
1.3.2 ... 6 years ago
1.3.1 ... 6 years ago
1.3.1-beta.1 ... 6 years ago
1.3.0 ... 6 years ago
1.3.0-beta.1 ... 6 years ago
1.2.0-beta.4 ... 6 years ago
1.2.0-beta.3 ... 6 years ago
1.2.0 ... 6 years ago
1.2.0-beta.2 ... 6 years ago
1.1.1 ... 6 years ago
1.2.0-beta.1 ... 6 years ago
1.1.0 ... 6 years ago
1.0.4 ... 6 years ago
1.0.3 ... 6 years ago
1.0.2 ... 6 years ago
1.0.1 ... 6 years ago
1.0.0 ... 6 years ago
1.0.0-alpha.10 ... 6 years ago
1.0.0-alpha.9 ... 6 years ago
1.0.0-alpha.8 ... 6 years ago
1.0.0-alpha.7 ... 6 years ago
1.0.0-alpha.6 ... 6 years ago
1.0.0-alpha.5 ... 6 years ago
1.0.0-alpha.4 ... 6 years ago
1.0.0-alpha.3 ... 6 years ago
1.0.0-alpha.2 ... 6 years ago
1.0.0-alpha.1 ... 6 years ago
1.0.0-alpha.0 ... 6 years ago
0.5.2 ... 6 years ago
0.5.1 ... 6 years ago
0.5.0 ... 6 years ago
0.4.15 ... 6 years ago
0.4.14 ... 6 years ago
0.4.13 ... 6 years ago
0.4.12 ... 6 years ago
0.4.11 ... 6 years ago
0.4.10 ... 6 years ago
0.4.9 ... 6 years ago
0.4.8 ... 6 years ago
0.4.7 ... 6 years ago
0.4.6 ... 6 years ago
0.4.5 ... 6 years ago
0.4.4 ... 6 years ago
0.4.3 ... 6 years ago
0.4.2 ... 6 years ago
0.4.1 ... 7 years ago
0.4.0 ... 7 years ago
0.3.0 ... 7 years ago
0.2.10 ... 7 years ago
0.2.9 ... 7 years ago
0.2.8 ... 7 years ago
0.2.7 ... 7 years ago
0.2.6 ... 7 years ago
0.2.5 ... 7 years ago
0.2.4 ... 7 years ago
0.2.3 ... 7 years ago
0.2.2 ... 7 years ago
0.2.1 ... 7 years ago
0.2.0 ... 7 years ago
0.1.5 ... 7 years ago
0.1.4 ... 7 years ago
0.1.3 ... 8 years ago
0.1.2 ... 8 years ago
0.1.1 ... 8 years ago
0.1.0 ... 8 years ago