Fork TS Checker Webpack Plugin
Webpack plugin that runs TypeScript type checker on a separate process.
[](https://www.npmjs.com/package/fork-ts-checker-webpack-plugin)
[](https://www.npmjs.com/package/fork-ts-checker-webpack-plugin)
[](https://travis-ci.org/TypeStrong/fork-ts-checker-webpack-plugin)
[](https://npmjs.org/package/fork-ts-checker-webpack-plugin)
[](http://commitizen.github.io/cz-cli/)
[](https://github.com/prettier/prettier)
[](https://github.com/semantic-release/semantic-release)
## Installation
This plugin requires minimum **webpack 2.3**, **TypeScript 2.1** and optionally **ESLint 6.0.0** or **TSLint 4.0**
```sh
# with npm
npm install --save-dev fork-ts-checker-webpack-plugin
# with yarn
yarn add --dev fork-ts-checker-webpack-plugin
```
Basic webpack config (with [ts-loader](https://github.com/TypeStrong/ts-loader))
```js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
const webpackConfig = {
context: __dirname, // to automatically find tsconfig.json
entry: './src/index.ts',
module: {
rules: [
{
test: /\.tsx?$/,
loader: 'ts-loader',
options: {
// disable type checker - we will use it in fork plugin
transpileOnly: true
}
}
]
},
plugins: [new ForkTsCheckerWebpackPlugin()]
};
```
## Motivation
There was already similar solution - [awesome-typescript-loader](https://github.com/s-panferov/awesome-typescript-loader). You can
add `CheckerPlugin` and delegate checker to the separate process. The problem with `awesome-typescript-loader` was that, in our case,
it was a lot slower than [ts-loader](https://github.com/TypeStrong/ts-loader) on an incremental build (~20s vs ~3s).
Secondly, we used [tslint](https://palantir.github.io/tslint) and we wanted to run this, along with type checker, in a separate process.
This is why this plugin was created. To provide better performance, the plugin reuses Abstract Syntax Trees between compilations and shares
these trees with TSLint. It can be scaled with a multi-process mode to utilize maximum CPU power.
## Modules resolution
It's very important to be aware that **this plugin uses [TypeScript](https://github.com/Microsoft/TypeScript)'s, not
[webpack](https://github.com/webpack/webpack)'s modules resolution**. It means that you have to setup `tsconfig.json` correctly. For example
if you set `files: ['./src/someFile.ts']` in `tsconfig.json`, this plugin will check only `someFile.ts` for semantic errors. It's because
of performance. The goal of this plugin is to be _as fast as possible_. With TypeScript's module resolution we don't have to wait for webpack
to compile files (which traverses dependency graph during compilation) - we have a full list of files from the begin.
To debug TypeScript's modules resolution, you can use `tsc --traceResolution` command.
## ESLint
[ESLint is the future of linting in the TypeScript world.](https://eslint.org/blog/2019/01/future-typescript-eslint) If you'd like to use eslint with the plugin, supply this option: `eslint: true` and ensure you have the relevant dependencies installed:
`yarn add eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --dev`
You should have an ESLint configuration file in your root project directory. Here is a sample `.eslintrc.js` configuration for a TypeScript project:
```js
const path = require('path');
module.exports = {
parser: '@typescript-eslint/parser', // Specifies the ESLint parser
extends: [
'plugin:@typescript-eslint/recommended' // Uses the recommended rules from the @typescript-eslint/eslint-plugin
],
parserOptions: {
project: path.resolve(__dirname, './tsconfig.json'),
tsconfigRootDir: __dirname,
ecmaVersion: 2018, // Allows for the parsing of modern ECMAScript features
sourceType: 'module', // Allows for the use of imports
},
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 [here](https://dev.to/robertcoopercode/using-eslint-and-prettier-in-a-typescript-project-53jb).
## TSLint
*[TSLint is being replaced by ESLint](https://medium.com/palantir/tslint-in-2019-1a144c2317a9).
https://eslint.org/blog/2019/01/future-typescript-eslint. As a consequence, support for TSLint in fork-ts-checker-webpack-plugin will be deprecated and removed in future versions of the plugin.*
If you have installed [tslint](https://palantir.github.io/tslint), you can enable it by setting `tslint: true` or
`tslint: './path/to/tslint.json'`. We recommend changing `defaultSeverity` to a `"warning"` in `tslint.json` file.
It helps to distinguish lints from TypeScript's diagnostics.
## Options
- **tsconfig** `string`:
Path to _tsconfig.json_ file. Default: `path.resolve(compiler.options.context, './tsconfig.json')`.
- **compilerOptions** `object`:
Allows overriding TypeScript options. Should be specified in the same format as you would do for the `compilerOptions` property in tsconfig.json. Default: `{}`.
- **eslint** `true | undefined`:
- If `true`, this activates eslint support.
- **eslintOptions** `object`:
- Options that can be used to initialise ESLint. See https://eslint.org/docs/1.0.0/developer-guide/nodejs-api#cliengine
- **tslint** `string | true | undefined`:
- If `string`, path to _tslint.json_ file to check source files against.
- If `true`, path to `tslint.json` file will be computed with respect to currently checked file, just like TSLint
CLI would do. Suppose you have a project:
```
./
tslint.json
src/
file.ts
anotherFile.ts
lib/
tslint.json
someHelperFile.ts
```
In such a case `src/file.ts` and `src/anotherFile.ts` would be checked against root `tslint.json`, and
`src/lib/someHelperFile.ts` would be checked against `src/lib/tslint.json`.
Default: `undefined`.
- **tslintAutoFix** `boolean`:
Passes on `--fix` flag while running `tslint` to auto fix linting errors. Default: false.
- **watch** `string | string[]`:
Directories or files to watch by service. Not necessary but improves performance (reduces number of `fs.stat` calls). Not applicable when `useTypescriptIncrementalApi` is `true`, in which case watching is handled automatically.
- **async** `boolean`:
True by default - `async: false` can block webpack's emit to wait for type checker/linter and to add errors to the webpack's compilation.
We recommend to set this to `false` in projects where type checking is faster than webpack's build - it's better for integration with other plugins. Another scenario where you might want to set this to `false` is if you use the `overlay` functionality of `webpack-dev-server`.
- **ignoreDiagnostics** `number[]`:
List of TypeScript diagnostic codes to ignore.
- **ignoreLints** `string[]`:
List of tslint rule names to ignore.
- **ignoreLintWarnings** `boolean`:
If true, will ignore all lint warnings.
- **reportFiles** `string[]`:
Only report errors on files matching these glob patterns. This can be useful when certain types definitions have errors that are not fatal to your application. Default: `[]`. Please note that this may behave unexpectedly if using the incremental API as the incremental API doesn't look for global and semantic errors [if it has already found syntactic errors](https://github.com/Microsoft/TypeScript/blob/89386ddda7dafc63cb35560e05412487f47cc267/src/compiler/watch.ts#L141).
```js
// in webpack.config.js
new ForkTsCheckerWebpackPlugin({
reportFiles: ['src/**/*.{ts,tsx}', '!src/skip.ts']
});
```
- **colors** `boolean`:
If `false`, disables built-in colors in logger messages. Default: `true`.
- **logger** `object`:
Logger instance. It should be object that implements method: `error`, `warn`, `info`. Default: `console`.
- **formatter** `'default' | 'codeframe' | ((message: NormalizedMessage, useColors: boolean) => string)`:
Formatter for diagnostics and lints. By default uses `default` formatter. You can also pass your own formatter as a function
(see `src/NormalizedMessage.js` and `src/formatter/` for api reference).
- **formatterOptions** `object`:
Options passed to formatters (currently only `codeframe` - see [available options](https://www.npmjs.com/package/babel-code-frame#options))
- **silent** `boolean`:
If `true`, logger will not be used. Default: `false`.
- **checkSyntacticErrors** `boolean`:
This option is useful if you're using ts-loader in `happyPackMode` with [HappyPack](https://github.com/amireh/happypack) or [thread-loader](https://github.com/webpack-contrib/thread-loader) to parallelise your builds. If `true` it will ensure that the plugin checks for _both_ syntactic errors (eg `const array = [{} {}];`) and semantic errors (eg `const x: number = '1';`). By default the plugin only checks for semantic errors. This is because when ts-loader is used in `transpileOnly` mode, ts-loader will still report syntactic errors. When used in `happyPackMode` it does not. Default: `false`.
- **memoryLimit** `number`:
Memory limit for service process in MB. If service exits with allocation failed error, increase this number. Default: `2048`.
- **workers** `number`:
You can split type checking to a few workers to speed-up increment build. **Be careful** - if you don't want to increase build time, you
should keep free 1 core for _build_ and 1 core for a _system_ _(for example system with 4 CPUs should use max 2 workers)_. Second thing -
node doesn't share memory between workers - keep in mind that memory usage will increase. Be aware that in some scenarios increasing workers
number **can increase checking time**. Default: `ForkTsCheckerWebpackPlugin.ONE_CPU`.
- **vue** `boolean | { enabled: boolean, compiler: string }`:
If `true` or `enabled: true`, the linter and compiler will process VueJs single-file-component (.vue) files. See the
[Vue section](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin#vue) further down for information on how to correctly setup your project.
- **useTypescriptIncrementalApi** `boolean`:
If true, the plugin will use incremental compilation API introduced in TypeScript 2.7. In this mode you can only have 1
worker, but if the changes in your code are small (like you normally have when you work in 'watch' mode), the compilation
may be much faster, even compared to multi-threaded compilation. Defaults to `true` when working with TypeScript 3+ and `false` when below 3. The default can be overridden by directly specifying a value.
- **measureCompilationTime** `boolean`:
If true, the plugin will measure the time spent inside the compilation code. This may be useful to compare modes,
especially if there are other loaders/plugins involved in the compilation. **requires node 8+**
- **typescript** `string`:
If supplied this is a custom path where `typescript` can be found. Defaults to `require.resolve('typescript')`.
- **resolveModuleNameModule** and **resolveTypeReferenceDirectiveModule** `string`:
Both of those options refer to files on the disk that respectively export a `resolveModuleName` or a `resolveTypeReferenceDirectiveModule` function. These functions will be used to resolve the import statements and the `