Merge pull request #10 from Realytics/feature/improve-readme

v0.1.5

Author: piotr-oles

CHANGELOG.md

@@ -1,3 +1,7 @@
+## v0.1.5
+ * Disable tslint if module is not installed and no tslint path is passed
+ * Improve README.md
+
 ## v0.1.4
  * Fix send to closed channel case
  * Fix removed files case

README.md

@@ -4,7 +4,7 @@
 
 Webpack plugin that runs typescript type checker on a separate process.
 
-## Installation ##
+## Installation
 This plugin requires minimum **webpack 2**, **typescript 2.1** and optionally **tslint 5.0**
 ```sh
 npm install --save-dev fork-ts-checker-webpack-plugin
@@ -41,52 +41,73 @@ var webpackConfig = {
 };
 ```
 
-## Motivation ##
+## Motivation
 There is 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 use [tslint](https://palantir.github.io/tslint/) and we wanted to run this, along with type checker, in a separate process.
+Secondly, we use [tslint](https://palantir.github.io/tslint) and we wanted to run this, along with type checker, in a separate process.
 This is why we've created this plugin. To provide better performance, 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.
 
-## Options ##
-**tsconfig** `string` - Path to tsconfig.json file. If not set, plugin will use `path.resolve(compiler.options.context, './tsconfig.json')`.
+## 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.
 
-**tslint** `string | false` - Path to tslint.json file. If not set, plugin will use `path.resolve(compiler.options.context, './tslint.json')`. 
-                              If `false`, disables tslint.
+To debug typescript's modules resolution, you can use `tsc --traceResolution` command.
 
-**watch** `string | string[]` - Directories or files to watch by service. Not necessary but improves performance 
-                                (reduces number of `fs.stat` calls).
+## TSLint
+If you have installed [tslint](https://palantir.github.io/tslint), it's enabled by default. To disable it, set `tslint: false` in plugin 
+options. We recommend changing `defaultSeverity` to the `"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')`
+
+* **tslint** `string | false`: 
+Path to tslint.json file. If `false`, disables tslint. Default: `path.resolve(compiler.options.context, './tslint.json')`
+
+* **watch** `string | string[]`: 
+Directories or files to watch by service. Not necessary but improves performance (reduces number of `fs.stat` calls).
 
-**blockEmit** `boolean` - If `true`, plugin will block emit until check will be done. It's good setting for ci/production build because 
-                          webpack will return code != 0 if there are type/lint errors. Default: `false`. 
+* **blockEmit** `boolean`: 
+If `true`, plugin will block emit until check will be done. It's good setting for ci/production build because webpack will return code != 0 
+if there are type/lint errors. Default: `false`. 
 
-**ignoreDiagnostics** `number[]` - List of typescript diagnostic codes to ignore.
+* **ignoreDiagnostics** `number[]`:
+List of typescript diagnostic codes to ignore.
 
-**ignoreLints** `string[]` - List of tslint rule names to ignore.
+* **ignoreLints** `string[]`: 
+List of tslint rule names to ignore.
 
-**colors** `boolean` - If `false`, disables built-in colors in logger messages. Default: `true`.
+* **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`.
+* **logger** `object`:
+Logger instance. It should be object that implements method: `error`, `warn`, `info`. Default: `console`.
 
-**silent** `boolean` - If `true`, logger will not be used. Default: `false`.
+* **silent** `boolean`:
+If `true`, logger will not be used. Default: `false`.
 
-**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`.
+* **memoryLimit** `number`: 
+Memory limit for service process in MB. If service exits with allocation failed error, increase this number. Default: `2048`.
 
-Pre-computed consts:      
+* **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`.
+
+### Pre-computed consts:      
   * `ForkTsCheckerWebpackPlugin.ONE_CPU` - always use one CPU
+  * `ForkTsCheckerWebpackPlugin.ALL_CPUS` - always use all CPUs (will increase build time)
   * `ForkTsCheckerWebpackPlugin.ONE_CPU_FREE` - leave only one CPU for build (probably will increase build time)
-  * `ForkTsCheckerWebpackPlugin.TWO_CPUS_FREE` - leave two CPUs free (one for build, one for system)
-
-**memoryLimit** `number` - Memory limit for service process in MB. If service exits with allocation failed error, increase this number.
-                           Default: `2048`.
+  * `ForkTsCheckerWebpackPlugin.TWO_CPUS_FREE` - **recommended** - leave two CPUs free (one for build, one for system)
 
-## Plugin Hooks ##
+## Plugin Hooks
 This plugin provides some custom webpack hooks (all are sync):
 
 | Event name | Description | Params |
@@ -100,5 +121,5 @@ This plugin provides some custom webpack hooks (all are sync):
 |`fork-ts-checker-emit`| Service will add errors and warnings to webpack compilation (`blockEmit: true`) | `diagnostics`, `lints`, `elapsed` |
 |`fork-ts-checker-done`| Service finished type checking and webpack finished compilation (`blockEmit: false`) | `diagnostics`, `lints`, `elapsed` |
 
-## License ##
+## License
 MIT

lib/index.js

@@ -16,9 +16,18 @@ var NormalizedMessage = require('./NormalizedMessage');
  * Options description in README.md
  */
 function ForkTsCheckerWebpackPlugin (options) {
+  var tslintInstalled;
+
+  try {
+    require.resolve('tslint');
+    tslintInstalled = true;
+  } catch (error) {
+    tslintInstalled = false;
+  }
+
   this.options = Object.assign({}, options);
   this.tsconfig = options.tsconfig || './tsconfig.json';
-  this.tslint = options.tslint === false ? false : options.tslint || './tslint.json';
+  this.tslint = options.tslint === false ? false : (options.tslint || (tslintInstalled ? './tslint.json' : false));
   this.watch = isString(options.watch) ? [options.watch] : options.watch || [];
   this.blockEmit = !!options.blockEmit;
   this.ignoreDiagnostics = options.ignoreDiagnostics || [];
@@ -55,8 +64,9 @@ module.exports = ForkTsCheckerWebpackPlugin;
 ForkTsCheckerWebpackPlugin.DEFAULT_MEMORY_LIMIT = 2048;
 
 ForkTsCheckerWebpackPlugin.ONE_CPU = 1;
-ForkTsCheckerWebpackPlugin.ONE_CPU_FREE = Math.max(1, os.cpus().length - 1);
-ForkTsCheckerWebpackPlugin.TWO_CPUS_FREE = Math.max(1, os.cpus().length - 2);
+ForkTsCheckerWebpackPlugin.ALL_CPUS = os.cpus().length;
+ForkTsCheckerWebpackPlugin.ONE_CPU_FREE = Math.max(1, ForkTsCheckerWebpackPlugin.ALL_CPUS - 1);
+ForkTsCheckerWebpackPlugin.TWO_CPUS_FREE = Math.max(1, ForkTsCheckerWebpackPlugin.ALL_CPUS - 2);
 
 ForkTsCheckerWebpackPlugin.prototype.apply = function (compiler) {
   this.compiler = compiler;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "fork-ts-checker-webpack-plugin",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Runs typescript type checker and linter on separate process.",
   "main": "lib/index.js",
   "scripts": {
@@ -23,7 +23,11 @@
     "linter",
     "fork",
     "fast",
-    "speed"
+    "speed",
+    "ts-loader",
+    "awesome-typescript-loader",
+    "increment",
+    "webpack-plugin"
   ],
   "author": "Piotr Oleś <[email protected]>",
   "license": "MIT",
@@ -38,7 +42,7 @@
     "mock-fs": "^4.3.0",
     "mock-require": "^2.0.2",
     "rimraf": "^2.5.4",
-    "sinon": "^2.2.0",
+    "sinon": "^2.3.1",
     "typescript": "^2.1.0"
   },
   "peerDependencies": {