|
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 | | -* **tslint** `string | true`: |
64 | | -Path to *tslint.json* file or `true`. If `true`, uses `path.resolve(compiler.options.context, './tslint.json')`. Default: `undefined`. |
65 | | - |
66 | | -* **watch** `string | string[]`: |
67 | | -Directories or files to watch by service. Not necessary but improves performance (reduces number of `fs.stat` calls). |
68 | | - |
69 | | -* **async** `boolean`: |
70 | | -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. |
71 | | -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`. |
72 | | - |
73 | | -* **ignoreDiagnostics** `number[]`: |
74 | | -List of typescript diagnostic codes to ignore. |
75 | | - |
76 | | -* **ignoreLints** `string[]`: |
77 | | -List of tslint rule names to ignore. |
78 | | - |
79 | | -* **colors** `boolean`: |
80 | | -If `false`, disables built-in colors in logger messages. Default: `true`. |
81 | | - |
82 | | -* **logger** `object`: |
83 | | -Logger instance. It should be object that implements method: `error`, `warn`, `info`. Default: `console`. |
84 | | - |
85 | | -* **formatter** `'default' | 'codeframe' | ((message: NormalizedMessage, useColors: boolean) => string)`: |
86 | | -Formatter for diagnostics and lints. By default uses `default` formatter. You can also pass your own formatter as a function |
87 | | -(see `src/NormalizedMessage.js` and `src/formatter/` for api reference). |
88 | | - |
89 | | -* **formatterOptions** `object`: |
90 | | -Options passed to formatters (currently only `codeframe` - see [available options](https://www.npmjs.com/package/babel-code-frame#options)) |
91 | | - |
92 | | -* **silent** `boolean`: |
93 | | -If `true`, logger will not be used. Default: `false`. |
94 | | - |
95 | | -* **checkSyntacticErrors** `boolean`: |
96 | | -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`. |
97 | | - |
98 | | -* **memoryLimit** `number`: |
99 | | -Memory limit for service process in MB. If service exits with allocation failed error, increase this number. Default: `2048`. |
100 | | - |
101 | | -* **workers** `number`: |
102 | | -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 |
103 | | -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 - |
104 | | -node doesn't share memory between workers - keep in mind that memory usage will increase. Be aware that in some scenarios increasing workers |
105 | | -number **can increase checking time**. Default: `ForkTsCheckerWebpackPlugin.ONE_CPU`. |
106 | | - |
107 | | -* **vue** `boolean`: |
108 | | -If `true`, the linter and compiler will process VueJs single-file-component (.vue) files. See the |
109 | | -[Vue section](https://github.com/Realytics/fork-ts-checker-webpack-plugin#vue) further down for information on how to correctly setup your project. |
110 | | - |
111 | | -### Pre-computed consts: |
112 | | - * `ForkTsCheckerWebpackPlugin.ONE_CPU` - always use one CPU |
113 | | - * `ForkTsCheckerWebpackPlugin.ALL_CPUS` - always use all CPUs (will increase build time) |
114 | | - * `ForkTsCheckerWebpackPlugin.ONE_CPU_FREE` - leave only one CPU for build (probably will increase build time) |
115 | | - * `ForkTsCheckerWebpackPlugin.TWO_CPUS_FREE` - **recommended** - leave two CPUs free (one for build, one for system) |
116 | | - |
117 | | -## Different behaviour in watch mode |
118 | | - |
119 | | -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. |
120 | | - |
121 | | -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. |
122 | | - |
123 | | -## Notifier |
124 | | - |
125 | | -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. |
126 | | - |
127 | | -## Known Issue Watching Non-Emitting Files |
128 | | - |
129 | | -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. |
130 | | - |
131 | | -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). |
132 | | - |
133 | | -## Plugin Hooks |
134 | | -This plugin provides some custom webpack hooks (all are sync): |
135 | | - |
136 | | -| Event name | Description | Params | |
137 | | -|------------|-------------|--------| |
138 | | -|`fork-ts-checker-cancel`| Cancellation has been requested | `cancellationToken` | |
139 | | -|`fork-ts-checker-waiting`| Waiting for results | `hasTsLint` | |
140 | | -|`fork-ts-checker-service-before-start`| Async plugin that can be used for delaying `fork-ts-checker-service-start` | - | |
141 | | -|`fork-ts-checker-service-start`| Service will be started | `tsconfigPath`, `tslintPath`, `watchPaths`, `workersNumber`, `memoryLimit` | |
142 | | -|`fork-ts-checker-service-start-error` | Cannot start service | `error` | |
143 | | -|`fork-ts-checker-service-out-of-memory`| Service is out of memory | - | |
144 | | -|`fork-ts-checker-receive`| Plugin receives diagnostics and lints from service | `diagnostics`, `lints` | |
145 | | -|`fork-ts-checker-emit`| Service will add errors and warnings to webpack compilation ('build' mode) | `diagnostics`, `lints`, `elapsed` | |
146 | | -|`fork-ts-checker-done`| Service finished type checking and webpack finished compilation ('watch' mode) | `diagnostics`, `lints`, `elapsed` | |
147 | | - |
148 | | -## Vue |
149 | | -1. Turn on the vue option in the plugin in your webpack config: |
150 | | - |
151 | | -``` |
152 | | - new ForkTsCheckerWebpackPlugin({ |
153 | | - tslint: true, |
154 | | - vue: true |
155 | | - }) |
156 | | -``` |
157 | | - |
158 | | -2. To activate TypeScript in your `.vue` files, you need to ensure your script tag's language attribute is set |
159 | | -to `ts` or `tsx` (also make sure you include the `.vue` extension in all your import statements as shown below): |
160 | | - |
161 | | -```html |
162 | | -<script lang="ts"> |
163 | | -import Hello from '@/components/hello.vue' |
164 | | -
|
165 | | -// ... |
166 | | -
|
167 | | -</script> |
168 | | -``` |
169 | | - |
170 | | -3. Ideally you are also using `ts-loader` (in transpileOnly mode). Your Webpack config rules may look something like this: |
171 | | - |
172 | | -``` |
173 | | -{ |
174 | | - test: /\.ts$/, |
175 | | - loader: 'ts-loader', |
176 | | - include: [resolve('src'), resolve('test')], |
177 | | - options: { |
178 | | - appendTsSuffixTo: [/\.vue$/], |
179 | | - transpileOnly: true |
180 | | - } |
181 | | -}, |
182 | | -{ |
183 | | - test: /\.vue$/, |
184 | | - loader: 'vue-loader', |
185 | | - options: vueLoaderConfig |
186 | | -}, |
187 | | -``` |
188 | | -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: |
189 | | - |
190 | | -```json |
191 | | -{ |
192 | | - "defaultSeverity": "error", |
193 | | - "extends": [ |
194 | | - "tslint-config-standard" |
195 | | - ] |
196 | | -} |
197 | | -``` |
198 | | -5. Ensure your `tsconfig.json` includes .vue files: |
199 | | - |
200 | | -``` |
201 | | -// tsconfig.json |
202 | | -{ |
203 | | - "include": [ |
204 | | - "src/**/*.ts", |
205 | | - "src/**/*.vue" |
206 | | - ], |
207 | | - "exclude": [ |
208 | | - "node_modules" |
209 | | - ] |
210 | | -} |
211 | | -``` |
212 | | - |
213 | | -6. It accepts any wildcard in your TypeScript configuration: |
214 | | -``` |
215 | | -// tsconfig.json |
216 | | -{ |
217 | | - "compilerOptions": { |
218 | | - |
219 | | - // ... |
220 | | -
|
221 | | - "baseUrl": ".", |
222 | | - "paths": { |
223 | | - "@/*": [ |
224 | | - "src/*" |
225 | | - ], |
226 | | - "~/*": [ |
227 | | - "src/*" |
228 | | - ] |
229 | | - } |
230 | | - } |
231 | | -} |
232 | | -
|
233 | | -// In a .ts or .vue file... |
234 | | -import Hello from '@/components/hello.vue' |
235 | | -``` |
236 | | - |
237 | | -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. |
238 | | - |
239 | | -## License |
240 | | -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