|
1 | | -# Fork TS Checker Webpack Plugin |
2 | | -[](https://www.npmjs.com/package/fork-ts-checker-webpack-plugin) |
3 | | -[](https://travis-ci.org/Realytics/fork-ts-checker-webpack-plugin) |
4 | | - |
5 | | -Webpack plugin that runs typescript type checker on a separate process. |
6 | | - |
7 | | -## Installation |
8 | | -This plugin requires minimum **webpack 2.3**, **typescript 2.1** and optionally **tslint 4.0** |
9 | | -```sh |
10 | | -npm install --save-dev fork-ts-checker-webpack-plugin |
11 | | -``` |
12 | | -Basic webpack config (with [ts-loader](https://github.com/TypeStrong/ts-loader)) |
13 | | -```js |
14 | | -var ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin'); |
15 | | - |
16 | | -var webpackConfig = { |
17 | | - context: __dirname, // to automatically find tsconfig.json |
18 | | - entry: './src/index.ts', |
19 | | - module: { |
20 | | - rules: [ |
21 | | - { |
22 | | - test: /\.tsx?$/, |
23 | | - loader: 'ts-loader', |
24 | | - options: { |
25 | | - // disable type checker - we will use it in fork plugin |
26 | | - transpileOnly: true |
27 | | - } |
28 | | - } |
29 | | - ] |
30 | | - }, |
31 | | - plugins: [ |
32 | | - new ForkTsCheckerWebpackPlugin() |
33 | | - ] |
34 | | -}; |
35 | | -``` |
36 | | - |
37 | | -## Motivation |
38 | | -There is already similar solution - [awesome-typescript-loader](https://github.com/s-panferov/awesome-typescript-loader). You can |
39 | | -add `CheckerPlugin` and delegate checker to the separate process. The problem with `awesome-typescript-loader` was that, in our case, |
40 | | -it was a lot slower than [ts-loader](https://github.com/TypeStrong/ts-loader) on an incremental build (~20s vs ~3s). |
41 | | -Secondly, we use [tslint](https://palantir.github.io/tslint) and we wanted to run this, along with type checker, in a separate process. |
42 | | -This is why we've created this plugin. To provide better performance, plugin reuses Abstract Syntax Trees between compilations and shares |
43 | | -these trees with tslint. It can be scaled with a multi-process mode to utilize maximum CPU power. |
44 | | - |
45 | | -## Modules resolution |
46 | | -It's very important to be aware that **this plugin uses [typescript](https://github.com/Microsoft/TypeScript)'s, not |
47 | | -[webpack](https://github.com/webpack/webpack)'s modules resolution**. It means that you have to setup `tsconfig.json` correctly. For example |
48 | | -if you set `files: ['./src/someFile.ts']` in `tsconfig.json`, this plugin will check only `someFile.ts` for semantic errors. It's because |
49 | | -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 |
50 | | -to compile files (which traverses dependency graph during compilation) - we have a full list of files from the begin. |
51 | | - |
52 | | -To debug typescript's modules resolution, you can use `tsc --traceResolution` command. |
53 | | - |
54 | | -## TSLint |
55 | | -If you have installed [tslint](https://palantir.github.io/tslint), you can enable it by setting `tslint: true` or |
56 | | -`tslint: './path/to/tslint.json'`. We recommend changing `defaultSeverity` to a `"warning"` in `tslint.json` file. |
57 | | -It helps to distinguish lints from typescript's diagnostics. |
58 | | - |
59 | | -## Options |
60 | | -* **tsconfig** `string`: |
61 | | -Path to *tsconfig.json* file. Default: `path.resolve(compiler.options.context, './tsconfig.json')`. |
62 | | - |
63 | | -* **compilerOptions** `object`: |
64 | | -Allows overriding TypeScript options. Should be specified in the same format as you would do for the `compilerOptions` property in tsconfig.json. Default: `{}`. |
65 | | - |
66 | | -* **tslint** `string | true`: |
67 | | -Path to *tslint.json* file or `true`. If `true`, uses `path.resolve(compiler.options.context, './tslint.json')`. Default: `undefined`. |
68 | | - |
69 | | -* **watch** `string | string[]`: |
70 | | -Directories or files to watch by service. Not necessary but improves performance (reduces number of `fs.stat` calls). |
71 | | - |
72 | | -* **async** `boolean`: |
73 | | -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. |
74 | | -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`. |
75 | | - |
76 | | -* **ignoreDiagnostics** `number[]`: |
77 | | -List of typescript diagnostic codes to ignore. |
78 | | - |
79 | | -* **ignoreLints** `string[]`: |
80 | | -List of tslint rule names to ignore. |
81 | | - |
82 | | -* **reportFiles** `string[]`: |
83 | | -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: `[]`. |
84 | | - |
85 | | -```js |
86 | | - // in webpack.config.js |
87 | | - new ForkTsCheckerWebpackPlugin({ reportFiles: ['src/**/*.{ts,tsx}', '!src/skip.ts'] }) |
88 | | -``` |
89 | | - |
90 | | -* **colors** `boolean`: |
91 | | -If `false`, disables built-in colors in logger messages. Default: `true`. |
92 | | - |
93 | | -* **logger** `object`: |
94 | | -Logger instance. It should be object that implements method: `error`, `warn`, `info`. Default: `console`. |
95 | | - |
96 | | -* **formatter** `'default' | 'codeframe' | ((message: NormalizedMessage, useColors: boolean) => string)`: |
97 | | -Formatter for diagnostics and lints. By default uses `default` formatter. You can also pass your own formatter as a function |
98 | | -(see `src/NormalizedMessage.js` and `src/formatter/` for api reference). |
99 | | - |
100 | | -* **formatterOptions** `object`: |
101 | | -Options passed to formatters (currently only `codeframe` - see [available options](https://www.npmjs.com/package/babel-code-frame#options)) |
102 | | - |
103 | | -* **silent** `boolean`: |
104 | | -If `true`, logger will not be used. Default: `false`. |
105 | | - |
106 | | -* **checkSyntacticErrors** `boolean`: |
107 | | -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. 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`. |
108 | | - |
109 | | -* **memoryLimit** `number`: |
110 | | -Memory limit for service process in MB. If service exits with allocation failed error, increase this number. Default: `2048`. |
111 | | - |
112 | | -* **workers** `number`: |
113 | | -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 |
114 | | -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 - |
115 | | -node doesn't share memory between workers - keep in mind that memory usage will increase. Be aware that in some scenarios increasing workers |
116 | | -number **can increase checking time**. Default: `ForkTsCheckerWebpackPlugin.ONE_CPU`. |
117 | | - |
118 | | -* **vue** `boolean`: |
119 | | -If `true`, the linter and compiler will process VueJs single-file-component (.vue) files. See the |
120 | | -[Vue section](https://github.com/Realytics/fork-ts-checker-webpack-plugin#vue) further down for information on how to correctly setup your project. |
121 | | - |
122 | | -### Pre-computed consts: |
123 | | - * `ForkTsCheckerWebpackPlugin.ONE_CPU` - always use one CPU |
124 | | - * `ForkTsCheckerWebpackPlugin.ALL_CPUS` - always use all CPUs (will increase build time) |
125 | | - * `ForkTsCheckerWebpackPlugin.ONE_CPU_FREE` - leave only one CPU for build (probably will increase build time) |
126 | | - * `ForkTsCheckerWebpackPlugin.TWO_CPUS_FREE` - **recommended** - leave two CPUs free (one for build, one for system) |
127 | | - |
128 | | -## Different behaviour in watch mode |
129 | | - |
130 | | -If you turn on [webpacks watch mode](https://webpack.js.org/configuration/watch/#watch) the `fork-ts-checker-notifier-webpack-plugin` will take care of logging type errors, _not_ webpack itself. That means if you set `silent: true` you won't see type errors in your console in watch mode. |
131 | | - |
132 | | -You can either set `silent: false` to show the logging from `fork-ts-checker-notifier-webpack-plugin` _or_ set `async: false`. Now webpack itself will log type errors again, but note that this can slow down your builds depending on the size of your project. |
133 | | - |
134 | | -## Notifier |
135 | | - |
136 | | -You may already be using the excellent [webpack-notifier](https://github.com/Turbo87/webpack-notifier) plugin to make build failures more obvious in the form of system notifications. There's an equivalent notifier plugin designed to work with the `fork-ts-checker-webpack-plugin`. It is the `fork-ts-checker-notifier-webpack-plugin` and can be found [here](https://github.com/johnnyreilly/fork-ts-checker-notifier-webpack-plugin). This notifier deliberately has a similar API as the `webpack-notifier` plugin to make migration easier. |
137 | | - |
138 | | -## Known Issue Watching Non-Emitting Files |
139 | | - |
140 | | -At present there is an issue with the plugin 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 which contains only `interface`s and / or `type`s then changes to it will **not** trigger the type checker whilst in watch mode. Sorry about that. |
141 | | - |
142 | | -We hope this will be resolved in future; the issue can be tracked [here](https://github.com/Realytics/fork-ts-checker-webpack-plugin/issues/36). |
143 | | - |
144 | | -## Plugin Hooks |
145 | | -This plugin provides some custom webpack hooks (all are sync): |
146 | | - |
147 | | -| Event name | Description | Params | |
148 | | -|------------|-------------|--------| |
149 | | -|`fork-ts-checker-cancel`| Cancellation has been requested | `cancellationToken` | |
150 | | -|`fork-ts-checker-waiting`| Waiting for results | `hasTsLint` | |
151 | | -|`fork-ts-checker-service-before-start`| Async plugin that can be used for delaying `fork-ts-checker-service-start` | - | |
152 | | -|`fork-ts-checker-service-start`| Service will be started | `tsconfigPath`, `tslintPath`, `watchPaths`, `workersNumber`, `memoryLimit` | |
153 | | -|`fork-ts-checker-service-start-error` | Cannot start service | `error` | |
154 | | -|`fork-ts-checker-service-out-of-memory`| Service is out of memory | - | |
155 | | -|`fork-ts-checker-receive`| Plugin receives diagnostics and lints from service | `diagnostics`, `lints` | |
156 | | -|`fork-ts-checker-emit`| Service will add errors and warnings to webpack compilation ('build' mode) | `diagnostics`, `lints`, `elapsed` | |
157 | | -|`fork-ts-checker-done`| Service finished type checking and webpack finished compilation ('watch' mode) | `diagnostics`, `lints`, `elapsed` | |
158 | | - |
159 | | -## Vue |
160 | | -1. Turn on the vue option in the plugin in your webpack config: |
161 | | - |
162 | | -``` |
163 | | - new ForkTsCheckerWebpackPlugin({ |
164 | | - tslint: true, |
165 | | - vue: true |
166 | | - }) |
167 | | -``` |
168 | | - |
169 | | -2. To activate TypeScript in your `.vue` files, you need to ensure your script tag's language attribute is set |
170 | | -to `ts` or `tsx` (also make sure you include the `.vue` extension in all your import statements as shown below): |
171 | | - |
172 | | -```html |
173 | | -<script lang="ts"> |
174 | | -import Hello from '@/components/hello.vue' |
175 | | -
|
176 | | -// ... |
177 | | -
|
178 | | -</script> |
179 | | -``` |
180 | | - |
181 | | -3. Ideally you are also using `ts-loader` (in transpileOnly mode). Your Webpack config rules may look something like this: |
182 | | - |
183 | | -``` |
184 | | -{ |
185 | | - test: /\.ts$/, |
186 | | - loader: 'ts-loader', |
187 | | - include: [resolve('src'), resolve('test')], |
188 | | - options: { |
189 | | - appendTsSuffixTo: [/\.vue$/], |
190 | | - transpileOnly: true |
191 | | - } |
192 | | -}, |
193 | | -{ |
194 | | - test: /\.vue$/, |
195 | | - loader: 'vue-loader', |
196 | | - options: vueLoaderConfig |
197 | | -}, |
198 | | -``` |
199 | | -4. Add rules to your `tslint.json` and they will be applied to Vue files. For example, you could apply the Standard JS rules [tslint-config-standard](https://github.com/blakeembrey/tslint-config-standard) like this: |
200 | | - |
201 | | -```json |
202 | | -{ |
203 | | - "defaultSeverity": "error", |
204 | | - "extends": [ |
205 | | - "tslint-config-standard" |
206 | | - ] |
207 | | -} |
208 | | -``` |
209 | | -5. Ensure your `tsconfig.json` includes .vue files: |
210 | | - |
211 | | -``` |
212 | | -// tsconfig.json |
213 | | -{ |
214 | | - "include": [ |
215 | | - "src/**/*.ts", |
216 | | - "src/**/*.vue" |
217 | | - ], |
218 | | - "exclude": [ |
219 | | - "node_modules" |
220 | | - ] |
221 | | -} |
222 | | -``` |
223 | | - |
224 | | -6. It accepts any wildcard in your TypeScript configuration: |
225 | | -``` |
226 | | -// tsconfig.json |
227 | | -{ |
228 | | - "compilerOptions": { |
229 | | - |
230 | | - // ... |
231 | | -
|
232 | | - "baseUrl": ".", |
233 | | - "paths": { |
234 | | - "@/*": [ |
235 | | - "src/*" |
236 | | - ], |
237 | | - "~/*": [ |
238 | | - "src/*" |
239 | | - ] |
240 | | - } |
241 | | - } |
242 | | -} |
243 | | -
|
244 | | -// In a .ts or .vue file... |
245 | | -import Hello from '@/components/hello.vue' |
246 | | -``` |
247 | | - |
248 | | -7. If you are working in **VSCode**, you can get extensions [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur) and [TSLint Vue](https://marketplace.visualstudio.com/items?itemName=prograhammer.tslint-vue) to complete the developer workflow. |
249 | | - |
250 | | -## License |
251 | | -MIT |
| 1 | +This is a fork of [`fork-ts-checker-webpack-plugin`](https://github.com/Realytics/fork-ts-checker-webpack-plugin). You probably want to use that package instead. |
0 commit comments