diff --git a/src/content/api/compilation-hooks.md b/src/content/api/compilation-hooks.md
new file mode 100644
index 000000000000..2adf68b0ac55
--- /dev/null
+++ b/src/content/api/compilation-hooks.md
@@ -0,0 +1,632 @@
+---
+title: Compilation Hooks
+group: Plugins
+sort: 2
+---
+
+The `Compilation` module is used by the `Compiler` to create new compilations
+(or builds). A `compilation` instance has access to all modules and their
+dependencies (most of which are circular references). It is the literal
+compilation of all the modules in the dependency graph of an application.
+During the compilation phase, modules are loaded, sealed, optimized, chunked,
+hashed and restored.
+
+The `Compilation` class also extends `Tapable` and provides the following
+lifecycle hooks. They can be tapped the same way as compiler hooks:
+
+``` js
+compilation.hooks.someHook.tap(...)
+```
+
+As with the `compiler`, `tapAsync` and `tapPromise` may also be available
+depending on the type of hook.
+
+
+### `buildModule`
+
+`SyncHook`
+
+Triggered before a module build has started.
+
+Parameters: `module`
+
+
+### `rebuildModule`
+
+`SyncHook`
+
+Fired before rebuilding a module.
+
+Parameters: `module`
+
+
+### `failedModule`
+
+`SyncHook`
+
+Run when a module build has failed.
+
+Parameters: `module` `error`
+
+
+### `succeedModule`
+
+`SyncHook`
+
+Executed when a module has been built successfully.
+
+Parameters: `module`
+
+
+### `finishModules`
+
+`SyncHook`
+
+All modules have been built.
+
+Parameters: `modules`
+
+
+### `finishRebuildingModule`
+
+`SyncHook`
+
+A module has been rebuilt.
+
+Parameters: `module`
+
+
+### `seal`
+
+`SyncHook`
+
+Fired when the compilation stops accepting new modules.
+
+
+### `unseal`
+
+`SyncHook`
+
+Fired when a compilation begins accepting new modules.
+
+
+### `optimizeDependenciesBasic`
+
+`SyncBailHook`
+
+...
+
+Parameters: `modules`
+
+
+### `optimizeDependencies`
+
+`SyncBailHook`
+
+Fired at the beginning of dependency optimization.
+
+Parameters: `modules`
+
+
+### `optimizeDependenciesAdvanced`
+
+`SyncBailHook`
+
+...
+
+Parameters: `modules`
+
+
+### `afterOptimizeDependencies`
+
+`SyncHook`
+
+...
+
+Parameters: `modules`
+
+
+### `optimize`
+
+`SyncHook`
+
+Triggered at the beginning of the optimization phase.
+
+
+### `optimizeModulesBasic`
+
+`SyncBailHook`
+
+...
+
+Parameters: `modules`
+
+
+### `optimizeModules`
+
+`SyncBailHook`
+
+...
+
+Parameters: `modules`
+
+
+### `optimizeModulesAdvanced`
+
+`SyncBailHook`
+
+...
+
+Parameters: `modules`
+
+
+### `afterOptimizeModules`
+
+`SyncHook`
+
+...
+
+Parameters: `modules`
+
+
+### `optimizeChunksBasic`
+
+`SyncBailHook`
+
+...
+
+Parameters: `chunks`
+
+
+### `optimizeChunks`
+
+`SyncBailHook`
+
+Optimize the chunks.
+
+Parameters: `chunks`
+
+
+### `optimizeChunksAdvanced`
+
+`SyncBailHook`
+
+...
+
+Parameters: `chunks`
+
+
+### `afterOptimizeChunks`
+
+`SyncHook`
+
+Fired after chunk optimization has completed.
+
+Parameters: `chunks`
+
+
+### `optimizeTree`
+
+`AsyncSeriesHook`
+
+Optimize the dependency tree asynchronously.
+
+Parameters: `chunks` `modules`
+
+
+### `afterOptimizeTree`
+
+`SyncHook`
+
+...
+
+Parameters: `chunks` `modules`
+
+
+### `optimizeChunkModulesBasic`
+
+`SyncBailHook`
+
+...
+
+Parameters: `chunks` `modules`
+
+
+### `optimizeChunkModules`
+
+`SyncBailHook`
+
+...
+
+Parameters: `chunks` `modules`
+
+
+### `optimizeChunkModulesAdvanced`
+
+`SyncBailHook`
+
+...
+
+Parameters: `chunks` `modules`
+
+
+### `afterOptimizeChunkModules`
+
+`SyncHook`
+
+...
+
+Parameters: `chunks` `modules`
+
+
+### `shouldRecord`
+
+`SyncBailHook`
+
+...
+
+
+### `reviveModules`
+
+`SyncHook`
+
+Restore module information from records.
+
+Parameters: `modules` `records`
+
+
+### `optimizeModuleOrder`
+
+`SyncHook`
+
+Sort the modules in from most to least important.
+
+Parameters: `modules`
+
+
+### `advancedOptimizeModuleOrder`
+
+`SyncHook`
+
+...
+
+Parameters: `modules`
+
+
+### `beforeModuleIds`
+
+`SyncHook`
+
+...
+
+Paramters: `modules`
+
+
+### `moduleIds`
+
+`SyncHook`
+
+...
+
+Parameters: `modules`
+
+
+### `optimizeModuleIds`
+
+`SyncHook`
+
+...
+
+Paramters: `chunks`
+
+
+### `afterOptimizeModuleIds`
+
+`SyncHook`
+
+...
+
+Paramters: `chunks`
+
+
+### `reviveChunks`
+
+`SyncHook`
+
+Restore chunk information from records.
+
+Parameters: `modules` `records`
+
+
+### `optimizeChunkOrder`
+
+`SyncHook`
+
+Sort the chunks in from most to least important.
+
+Parameters: `chunks`
+
+
+### `beforeOptimizeChunkIds`
+
+`SyncHook`
+
+Fired before chunk `id` optimization.
+
+Paramters: `chunks`
+
+
+### `optimizeChunkIds`
+
+`SyncHook`
+
+Optimize the `id` of each chunk.
+
+Parameters: `chunks`
+
+
+### `afterOptimizeChunkIds`
+
+`SyncHook`
+
+Triggered after chunk `id` optimization has finished.
+
+Paramters: `chunks`
+
+
+### `recordModules`
+
+`SyncHook`
+
+Store module info to the records.
+
+Parameters: `modules` `records`
+
+
+### `recordChunks`
+
+`SyncHook`
+
+Store chunk info to the records.
+
+Parameters: `chunks` `records`
+
+
+### `beforeHash`
+
+`SyncHook`
+
+Before the compilation is hashed.
+
+
+### `afterHash`
+
+`SyncHook`
+
+After the compilation is hashed.
+
+
+### `recordHash`
+
+`SyncHook`
+
+...
+
+Parameters: `records`
+
+
+### `record`
+
+`SyncHook`
+
+Store information about the `compilation` to the `records`.
+
+Parameters: `compilation` `records`
+
+
+### `beforeModuleAssets`
+
+`SyncHook`
+
+...
+
+
+### `shouldGenerateChunkAssets`
+
+`SyncBailHook`
+
+...
+
+
+### `beforeChunkAssets`
+
+`SyncHook`
+
+Before creating the chunk assets.
+
+
+### `additionalChunkAssets`
+
+`SyncHook`
+
+Create additional assets for the chunks.
+
+Parameters: `chunks`
+
+
+### `records`
+
+`SyncHook`
+
+...
+
+Parameters: `compilation` `records`
+
+
+### `additionalAssets`
+
+`AsyncSeriesHook`
+
+Create additional assets for the compilation. This hook can be used to download
+an image, for example:
+
+``` js
+compilation.hooks.additionalAssets.tapAsync('MyPlugin', callback => {
+ download('https://img.shields.io/npm/v/webpack.svg', function(resp) {
+ if(resp.status === 200) {
+ compilation.assets['webpack-version.svg'] = toAsset(resp);
+ callback();
+ } else {
+ callback(new Error('[webpack-example-plugin] Unable to download the image'));
+ }
+ })
+});
+```
+
+
+### `optimizeChunkAssets`
+
+`AsyncSeriesHook`
+
+Optimize any chunk assets. The assets are stored in `compilation.assets`. A
+`Chunk` has a property `files` which points to all files created by a chunk.
+Any additional chunk assets are stored in `compilation.additionalChunkAssets`.
+
+Parameters: `chunks`
+
+Here's an example that simply adds a banner to each chunk.
+
+``` js
+compilation.hooks
+ .optimizeChunkAssets
+ .tapAsync('MyPlugin', (chunks, callback) => {
+ chunks.forEach(chunk => {
+ chunk.files.forEach(file => {
+ compilation.assets[file] = new ConcatSource(
+ '\/**Sweet Banner**\/',
+ '\n',
+ compilation.assets[file]
+ );
+ });
+ });
+
+ callback();
+ });
+```
+
+
+### `afterOptimizeChunkAssets`
+
+`SyncHook`
+
+The chunk assets have been optimized.
+
+Parameters: `chunks`
+
+Here's an example plugin from [@boopathi](https://github.com/boopathi) that outputs exactly what went into each chunk.
+
+``` js
+compilation.hooks.afterOptimizeChunkAssets.tap(chunks => {
+ chunks.forEach(chunk => {
+ console.log({
+ id: chunk.id,
+ name: chunk.name,
+ includes: chunk.modules.map(module => module.request)
+ });
+ });
+});
+```
+
+
+### `optimizeAssets`
+
+`AsyncSeriesHook`
+
+Optimize all assets stored in `compilation.assets`.
+
+Parameters: `assets`
+
+
+### `afterOptimizeAssets`
+
+`SyncHook`
+
+The assets has been optimized.
+
+Parameters: `assets`
+
+
+### `needAdditionalSeal`
+
+`SyncBailHook`
+
+...
+
+
+### `afterSeal`
+
+`AsyncSeriesHook`
+
+...
+
+
+### `chunkHash`
+
+`SyncHook`
+
+...
+
+Parameters: `chunk` `chunkHash`
+
+
+### `moduleAsset`
+
+`SyncHook`
+
+An asset from a module was added to the compilation.
+
+Parameters: `module` `filename`
+
+
+### `chunkAsset`
+
+`SyncHook`
+
+An asset from a chunk was added to the compilation.
+
+Parameters: `chunk` `filename`
+
+
+### `assetPath`
+
+`SyncWaterfallHook`
+
+...
+
+Parameters: `filename` `data`
+
+
+### `needAdditionalPass`
+
+`SyncBailHook`
+
+...
+
+
+### `childCompiler`
+
+`SyncHook`
+
+...
+
+Parameters: `childCompiler` `compilerName` `compilerIndex`
+
+
+### `normalModuleLoader`
+
+`SyncHook`
+
+The normal module loader is the function that actually loads all the modules
+in the module graph (one-by-one).
+
+Parameters: `loaderContext` `module`
diff --git a/src/content/api/compilation.md b/src/content/api/compilation.md
deleted file mode 100644
index 56e0d1c1448a..000000000000
--- a/src/content/api/compilation.md
+++ /dev/null
@@ -1,296 +0,0 @@
----
-title: Compilation
-group: Plugins
-sort: 3
----
-
-The Compilation instance extends from the compiler i.e. `compiler.compilation`. It is the literal compilation of all the objects in the require graph. This object has access to all the modules and their dependencies (most of which are circular references). In the compilation phase, modules are loaded, sealed, optimized, chunked, hashed and restored, etc. This would be the main lifecycle of any operations of the compilation.
-
-``` js
-compiler.plugin("compilation", function(compilation) {
- // the main compilation instance
- // all subsequent methods are derived from compilation.plugin
-});
-```
-
-
-## `normal-module-loader`
-
-The normal module loader, is the function that actually loads all the modules in the module graph (one-by-one).
-
-``` js
-compilation.plugin('normal-module-loader', function(loaderContext, module) {
- // this is where all the modules are loaded
- // one by one, no dependencies are created yet
-});
-```
-
-
-## `seal`
-
-The sealing of the compilation has started.
-
-``` js
-compilation.plugin('seal', function() {
- // you are not accepting any more modules
- // no arguments
-});
-```
-
-
-## `optimize`
-
-Optimize the compilation.
-
-``` js
-compilation.plugin('optimize', function() {
- // webpack is begining the optimization phase
- // no arguments
-});
-```
-
-
-## `optimize-tree(chunks, modules)` async
-
-Async optimization of the tree.
-
-``` js
-compilation.plugin('optimize-tree', function(chunks, modules) {
-
-});
-```
-
-### `optimize-modules(modules: Module[])`
-
-Optimize the modules.
-
-``` js
-compilation.plugin('optimize-modules', function(modules) {
- // handle to the modules array during tree optimization
-});
-```
-
-
-## `after-optimize-modules(modules: Module[])`
-
-Optimizing the modules has finished.
-
-
-## `optimize-chunks(chunks: Chunk[])`
-
-Optimize the chunks.
-
-```javascript
-//optimize chunks may be run several times in a compilation
-
-compilation.plugin('optimize-chunks', function(chunks) {
- // Unless you've specified multiple entries in your config
- // there's only one chunk at this point
- chunks.forEach(function (chunk) {
- // Chunks have circular references to their modules
- chunk.modules.forEach(function (module){
- // module.loaders, module.rawRequest, module.dependencies, etc.
- });
- });
-});
-```
-
-## `after-optimize-chunks(chunks: Chunk[])`
-
-Optimizing the chunks has finished.
-
-
-## `revive-modules(modules: Module[], records)`
-
-Restore module info from records.
-
-
-## `optimize-module-order(modules: Module[])`
-
-Sort the modules in order of importance. The first is the most important module. It will get the smallest id.
-
-
-## `optimize-module-ids(modules: Module[])`
-
-Optimize the module ids.
-
-
-## `after-optimize-module-ids(modules: Module[])`
-
-Optimizing the module ids has finished.
-
-
-## `record-modules(modules: Module[], records)`
-
-Store module info to the records.
-
-
-## `revive-chunks(chunks: Chunk[], records)`
-
-Restore chunk info from records.
-
-
-## `optimize-chunk-order(chunks: Chunk[])`
-
-Sort the chunks in order of importance. The first is the most important chunk. It will get the smallest id.
-
-
-## `optimize-chunk-ids(chunks: Chunk[])`
-
-Optimize the chunk ids.
-
-
-## `after-optimize-chunk-ids(chunks: Chunk[])`
-
-Optimizing the chunk ids has finished.
-
-
-## `record-chunks(chunks: Chunk[], records)`
-
-Store chunk info to the records.
-
-
-## `before-hash`
-
-Before the compilation is hashed.
-
-
-## `after-hash`
-
-After the compilation is hashed.
-
-
-## `before-chunk-assets`
-
-Before creating the chunk assets.
-
-
-## `additional-chunk-assets(chunks: Chunk[])`
-
-Create additional assets for the chunks.
-
-
-## `record(compilation, records)`
-
-Store info about the compilation to the records
-
-
-## `additional-assets` async
-
-Create additional assets for the compilation
-
-Here's an example that downloads an image.
-
-``` js
-compiler.plugin('compilation', function(compilation) {
- compilation.plugin('additional-assets', function(callback) {
- download('https://img.shields.io/npm/v/webpack.svg', function(resp) {
- if(resp.status === 200) {
- compilation.assets['webpack-version.svg'] = toAsset(resp);
- callback();
- } else {
- callback(new Error('[webpack-example-plugin] Unable to download the image'));
- }
- })
- });
-});
-```
-
-
-## `optimize-chunk-assets(chunks: Chunk[])` async
-
-Optimize the assets for the chunks.
-
-The assets are stored in `this.assets`, but not all of them are chunk assets. A `Chunk` has a property `files` which points to all files created by this chunk. The additional chunk assets are stored in `this.additionalChunkAssets`.
-
-Here's an example that simply adds a banner to each chunk.
-
-``` js
-compilation.plugin("optimize-chunk-assets", function(chunks, callback) {
- chunks.forEach(function(chunk) {
- chunk.files.forEach(function(file) {
- compilation.assets[file] = new ConcatSource("\/**Sweet Banner**\/", "\n", compilation.assets[file]);
- });
- });
- callback();
-});
-```
-
-## `after-optimize-chunk-assets(chunks: Chunk[])`
-
-The chunk assets have been optimized. Here's an example plugin from [@boopathi](https://github.com/boopathi) that outputs exactly what went into each chunk.
-
-``` js
-var PrintChunksPlugin = function() {};
-
-PrintChunksPlugin.prototype.apply = function(compiler) {
- compiler.plugin('compilation', function(compilation, params) {
- compilation.plugin('after-optimize-chunk-assets', function(chunks) {
- console.log(chunks.map(function(c) {
- return {
- id: c.id,
- name: c.name,
- includes: c.modules.map(function(m) {
- return m.request;
- })
- };
- }));
- });
- });
-};
-```
-
-
-## `optimize-assets(assets: Object{name: Source})` async
-
-Optimize all assets.
-
-The assets are stored in `this.assets`.
-
-
-## `after-optimize-assets(assets: Object{name: Source})`
-
-The assets has been optimized.
-
-
-## `build-module(module)`
-
-Before a module build has started.
-
-``` js
-compilation.plugin('build-module', function(module){
- console.log('About to build: ', module);
-});
-```
-
-
-## `succeed-module(module)`
-
-A module has been built successfully.
-
-``` js
-compilation.plugin('succeed-module', function(module){
- console.log('Successfully built: ', module);
-});
-```
-
-
-## `failed-module(module)`
-
-The module build has failed.
-
-``` js
-compilation.plugin('failed-module', function(module){
- console.log('Failed to build: ', module);
-});
-```
-
-
-## `module-asset(module, filename)`
-
-An asset from a module was added to the compilation.
-
-
-## `chunk-asset(chunk, filename)`
-
-An asset from a chunk was added to the compilation.
diff --git a/src/content/api/compiler-hooks.md b/src/content/api/compiler-hooks.md
new file mode 100644
index 000000000000..a3e3f5cf26d0
--- /dev/null
+++ b/src/content/api/compiler-hooks.md
@@ -0,0 +1,244 @@
+---
+title: Compiler Hooks
+group: Plugins
+sort: 1
+contributors:
+ - rishantagarwal
+---
+
+The `Compiler` module is the main engine that creates a compilation instance
+with all the options passed through the [CLI]() or [Node API](). It extends the
+`Tapable` class in order to register and call plugins. Most user facing plugins
+are first registered on the `Compiler`.
+
+T> This module is exposed as `webpack.Compiler` and can be used directly.See
+[this example](https://github.com/pksjce/webpack-internal-examples/tree/master/compiler-example)
+for more information.
+
+
+## Watching
+
+The `Compiler` supports [watching](/api/node/#watching) which monitors the file
+system and recompiles as files change. When in watch mode, the compiler will
+emit the additional events such as `watchRun`, `watchClose`, and `invalid`.
+This is typically used in [development](/guides/development), usually under
+the hood of tools like `webpack-dev-server`, so that the developer doesn't
+need to re-compile manually every time. Watch mode can also be entered via the
+[CLI](/api/cli/#watch-options).
+
+
+## Hooks
+
+The following lifecycle hooks are exposed by the `compiler` and can be accessed
+as such:
+
+``` js
+compiler.hooks.someHook.tap(...)
+```
+
+Depending on the hook type, `tapAsync` and `tapPromise` may also be available.
+
+
+### `entryOption`
+
+`SyncBailHook`
+
+Executes a plugin after the `entry` configuration has been processed.
+
+
+### `afterPlugins`
+
+`SyncHook`
+
+Runs a plugin after setting up initial set of plugins.
+
+Parameters: `compiler`
+
+
+### `afterResolvers`
+
+`SyncHook`
+
+Executes a plugin after resolver setup is complete.
+
+Parameters: `compiler`
+
+
+### `environment`
+
+`SyncHook`
+
+Runs a plugin before the environment is prepared.
+
+
+### `afterEnvironment`
+
+`SyncHook`
+
+Executes a plugin a environment setup is complete.
+
+
+### `beforeRun`
+
+`AsyncSeriesHook`
+
+Adds a hook right before `compiler.run()` is executed.
+
+Parameters: `compiler`
+
+
+### `run`
+
+`AsyncSeriesHook`
+
+Hook into the compiler before it begins reading records.
+
+Parameters: `compiler`
+
+
+### `watchRun`
+
+`AsyncSeriesHook`
+
+Executes a plugin during watch mode after a new compilation is triggered
+but before the compilation is actually started.
+
+Parameters: `compiler`
+
+
+### `normalModuleFactory`
+
+`SyncHook`
+
+Runs a plugin after a `NormalModuleFactory` is created.
+
+Parameters: `normalModuleFactory`
+
+
+### `contextModuleFactory`
+
+Runs a plugin after a `ContextModuleFactory` is created.
+
+Parameters: `contextModuleFactory`
+
+
+### `beforeCompile`
+
+`AsyncSeriesHook`
+
+Executes a plugin after compilation parameters are created.
+
+Parameters: `compilationParams`
+
+
+### `compile`
+
+`SyncHook`
+
+Hook into the compiler before a new compilation is created.
+
+Parameters: `compilationParams`
+
+
+### `thisCompilation`
+
+`SyncHook`
+
+Executed before emitting the `compilation` event (see below).
+
+Parameters: `compilation`
+
+
+### `compilation`
+
+`SyncHook`
+
+Runs a plugin after a compilation has been created.
+
+Parameters: `compilation`
+
+
+### `make`
+
+`AsyncParallelHook`
+
+...
+
+Parameters: `compilation`
+
+
+### `afterCompile`
+
+`AsyncSeriesHook`
+
+...
+
+Parameters: `compilation`
+
+
+### `shouldEmit`
+
+`SyncBailHook`
+
+Can return true/false at this point
+
+Parameters: `compilation`
+
+
+### `needAdditionalPass`
+
+`SyncBailHook`
+
+...
+
+
+### `emit`
+
+`AsyncSeriesHook`
+
+Before emitting assets to output dir
+
+Parameters: `compilation`
+
+
+### `afterEmit`
+
+`AsyncSeriesHook`
+
+After emitting assets to output dir
+
+Parameters: `compilation`
+
+
+### `done`
+
+`SyncHook`
+
+Compilation has completed.
+
+Parameters: `stats`
+
+
+### `failed`
+
+`SyncHook`
+
+Compilation has failed.
+
+Parameters: `error`
+
+
+### `invalid`
+
+`SyncHook`
+
+Watch compilation has been invalidated.
+
+Parameters: `fileName`, `changeTime`
+
+
+### `watchClose`
+
+`SyncHook`
+
+Watch mode has stopped.
diff --git a/src/content/api/compiler.md b/src/content/api/compiler.md
deleted file mode 100644
index bc303a0a78cb..000000000000
--- a/src/content/api/compiler.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-title: Compiler
-group: Plugins
-sort: 2
-contributors:
- - rishantagarwal
----
-
-The `Compiler` module of webpack is the main engine that creates a compilation instance with all the options passed through webpack CLI or `webpack` api or webpack configuration file.
-
-It is exported by `webpack` api under `webpack.Compiler`.
-
-The compiler is used by webpack by instantiating it and then calling the `run` method. Below is a trivial example of how one might use the `Compiler`. In fact, this is really close to how webpack itself uses it.
-
-[__compiler-example__](https://github.com/pksjce/webpack-internal-examples/tree/master/compiler-example)
-
-```javascript
-// Can be imported from webpack package
-import {Compiler} from 'webpack';
-
-// Create a new compiler instance
-const compiler = new Compiler();
-
-// Populate all required options
-compiler.options = {...};
-
-// Creating a plugin.
-class LogPlugin {
- apply (compiler) {
- compiler.plugin('should-emit', compilation => {
- console.log('should I emit?');
- return true;
- })
- }
-}
-
-// Apply the compiler to the plugin
-new LogPlugin().apply(compiler);
-
-/* Add other supporting plugins */
-
-// Callback to be executed after run is complete
-const callback = (err, stats) => {
- console.log('Compiler has finished execution.');
- // Display stats...
-};
-
-// call run on the compiler along with the callback
-compiler.run(callback);
-```
-
-The `Compiler` is what we call a `Tapable` instance. By this, we mean that it mixes in `Tapable` class to imbibe functionality to register and call plugins on itself. Most user facing plugins are first registered on the `Compiler`. The working of a Compiler can be condensed into the following highlights
-
-- Usually there is one master instance of Compiler. Child compilers can be created for delegating specific tasks.
-- A lot of the complexity in creating a compiler goes into populating all the relevant options for it.
-- `webpack` has [`WebpackOptionsDefaulter`](https://github.com/webpack/webpack/blob/master/lib/WebpackOptionsDefaulter.js) and [`WebpackOptionsApply`](https://github.com/webpack/webpack/blob/master/lib/WebpackOptionsApply.js) specifically designed to provide the `Compiler` with all the initial data it requires.
-- The `Compiler` is ultimately just a function which performs bare minimum functionality to keep a lifecycle running. It delegates all the loading/bundling/writing work to various plugins.
-- `new LogPlugin(args).apply(compiler)` registers the plugin to any particular hook event in the `Compiler`'s lifecycle.
-- The `Compiler` exposes a `run` method which kickstarts all compilation work for `webpack`. When that is done, it should call the passed in `callback` function. All the tail end work of logging stats and errors are done in this callback function.
-
-
-## Watching
-
-The `Compiler` supports "watch mode" which monitors the file system and recompiles as files change. When in watch mode, the compiler will emit the additional events ["watch-run", "watch-close", and "invalid"](#event-hooks). This is typically used in [development](/guides/development), usually under the hood of tools like `webpack-dev-server`, so that the developer doesn't need to re-compile manually every time.
-
-For more details about watch mode, see the [Node.js API documentation](/api/node/#watching) or the [CLI watch options](/api/cli/#watch-options).
-
-
-## MultiCompiler
-
-This module, MultiCompiler, allows webpack to run multiple configurations in separate compiler.
-If the `options` parameter in the webpack's NodeJS api is an array of options, webpack applies separate compilers and calls the `callback` method at the end of each compiler execution.
-
-```javascript
-var webpack = require('webpack');
-
-var config1 = {
- entry: './index1.js',
- output: {filename: 'bundle1.js'}
-}
-var config2 = {
- entry: './index2.js',
- output: {filename:'bundle2.js'}
-}
-
-webpack([config1, config2], (err, stats) => {
- process.stdout.write(stats.toString() + "\n");
-})
-```
-
-
-## Event Hooks
-
-This a reference guide to all the event hooks exposed by the `Compiler`.
-
-Event name | Reason | Params | Type
------------------------------ | --------------------------------------- | ------------------------- | ----------
-__`entry-option`__ | - | - | bailResult
-__`after-plugins`__ | After setting up initial set of plugins | `compiler` | sync
-__`after-resolvers`__ | After setting up the resolvers | `compiler` | sync
-__`environment`__ | - | - | sync
-__`after-environment`__ | Environment setup complete | - | sync
-__`before-run`__ | `compiler.run()` starts | `compiler` | async
-__`run`__ | Before reading records | `compiler` | async
-__`watch-run`__ | Before starting compilation after watch | `compiler` | async
-__`normal-module-factory`__ | After creating a `NormalModuleFactory` | `normalModuleFactory` | sync
-__`context-module-factory`__ | After creating a `ContextModuleFactory` | `contextModuleFactory` | sync
-__`before-compile`__ | Compilation parameters created | `compilationParams` | async
-__`compile`__ | Before creating new compilation | `compilationParams` | sync
-__`this-compilation`__ | Before emitting `compilation` event | `compilation` | sync
-__`compilation`__ | Compilation creation completed | `compilation` | sync
-__`make`__ | - | `compilation` | parallel
-__`after-compile`__ | - | `compilation` | async
-__`should-emit`__ | Can return true/false at this point | `compilation` | bailResult
-__`need-additional-pass`__ | - | - | bailResult
-__`emit`__ | Before emitting assets to output dir | `compilation` | async
-__`after-emit`__ | After emitting assets to output dir | `compilation` | async
-__`done`__ | Completion of compile | `stats` | sync
-__`failed`__ | Failure of compile | `error` | sync
-__`invalid`__ | After invalidating a watch compile | `fileName`, `changeTime` | sync
-__`watch-close`__ | After stopping a watch compile | - | sync
-
-
-## Usage
-
-Here's an example of an asynchronous `emit` event handler:
-
-```javascript
-compiler.plugin("emit", function(compilation, callback) {
- // Do something async...
- setTimeout(function() {
- console.log("Done with async work...");
- callback();
- }, 1000);
-});
-```
diff --git a/src/content/api/index.md b/src/content/api/index.md
index 9ae94b03c03b..817fe57831e9 100644
--- a/src/content/api/index.md
+++ b/src/content/api/index.md
@@ -5,39 +5,55 @@ contributors:
- tbroadley
---
-A variety of interfaces are available to customize the compilation process. Some features overlap between interfaces, e.g. a configuration option may be available via a CLI flag, while others exist only through a single interface. The following high-level information should get you started.
+A variety of interfaces are available to customize the compilation process.
+Some features overlap between interfaces, e.g. a configuration option may be
+available via a CLI flag, while others exist only through a single interface.
+The following high-level information should get you started.
## CLI
-The Command Line Interface (CLI) to configure and interact with your build. It is especially useful in the case of early prototyping and profiling. For the most part, the CLI is simply used to kick off the process using a configuration file and a few flags (e.g. `--env`).
+The Command Line Interface (CLI) to configure and interact with your build. It
+is especially useful in the case of early prototyping and profiling. For the
+most part, the CLI is simply used to kick off the process using a configuration
+file and a few flags (e.g. `--env`).
[Learn more!](/api/cli)
## Module
-When processing modules with webpack, it is important to understand the different module syntaxes -- specifically the [methods](/api/module-methods) and [variables](/api/module-variables) -- that are supported.
+When processing modules with webpack, it is important to understand the
+different module syntaxes -- specifically the [methods](/api/module-methods)
+and [variables](/api/module-variables) -- that are supported.
[Learn more!](/api/module-methods)
## Node
-While most users can get away with just using the CLI along with a configuration file, more fine-grained control of the compilation can be achieved via the Node interface. This includes passing multiple configurations, programmatically running or watching, and collecting stats.
+While most users can get away with just using the CLI along with a
+configuration file, more fine-grained control of the compilation can be
+achieved via the Node interface. This includes passing multiple configurations,
+programmatically running or watching, and collecting stats.
[Learn more!](/api/node)
## Loaders
-Loaders are transformations that are applied to the source code of a module. They are written as functions that accept source code as a parameter and return a new version of that code with transformations applied.
+Loaders are transformations that are applied to the source code of a module.
+They are written as functions that accept source code as a parameter and return
+a new version of that code with transformations applied.
[Learn more!](/api/loaders)
## Plugins
-The plugin interface provided by webpack allows users to tap directly into the compilation process. Plugins can register handlers on lifecycle hooks that run at different points in the compilation process. When each hook is executed, the plugin will have full access to the current state of the compilation.
+The plugin interface allows users to tap directly into the compilation process.
+Plugins can register handlers on lifecycle hooks that run at different points
+throughout a compilation. When each hook is executed, the plugin will have full
+access to the current state of the compilation.
[Learn more!](/api/plugins)
diff --git a/src/content/api/module-factories.md b/src/content/api/module-factories.md
deleted file mode 100644
index fd2471ab1e7c..000000000000
--- a/src/content/api/module-factories.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-title: Module Factories
-group: Plugins
-sort: 5
----
-
-?> Lead in...
-
-## `NormalModuleFactory`
-
-`before-resolve(data)` async waterfall
-
-Before the factory starts resolving. The `data` object has these properties:
-
-* `context`: The absolute path of the directory for resolving.
-* `request`: The request of the expression.
-
-Plugins are allowed to modify the object or to pass a new similar object to the callback.
-
-`after-resolve(data)` async waterfall
-
-After the factory has resolved the request. The `data` object has these properties:
-
-* `request`: The resolved request. It acts as an identifier for the NormalModule.
-* `userRequest`: The request the user entered. It's resolved, but does not contain pre or post loaders.
-* `rawRequest`: The unresolved request.
-* `loaders`: A array of resolved loaders. This is passed to the NormalModule and they will be executed.
-* `resource`: The resource. It will be loaded by the NormalModule.
-* `parser`: The parser that will be used by the NormalModule.
-
-
-## `ContextModuleFactory`
-
-`before-resolve(data)` async waterfall
-
-?> Add documentation.
-
-`after-resolve(data)` async waterfall
-
-?> Add documentation.
-
-`alternatives(options: Array)` async waterfall
-
-?> Add documentation.
diff --git a/src/content/api/node.md b/src/content/api/node.md
index 5668bf201bfa..613064a2455f 100644
--- a/src/content/api/node.md
+++ b/src/content/api/node.md
@@ -48,34 +48,47 @@ webpack({
T> The `err` object **will not** include compilation errors and those must be handled separately using `stats.hasErrors()` which will be covered in detail in [Error Handling](#error-handling) section of this guide. The `err` object will only contain webpack-related issues, such as misconfiguration, etc.
-**Note** that you can provide the `webpack` function with an array of configurations:
+T> You can provide the `webpack` function with an array of configurations. See
+the [MultiCompiler](#multicompiler) section below for more information.
-``` js-with-links
-webpack([
- { /* Configuration Object */ },
- { /* Configuration Object */ },
- { /* Configuration Object */ }
-], (err, [stats](#stats-object)) => {
- // ...
-});
-```
-T> webpack will **not** run the multiple configurations in parallel. Each configuration is only processed after the previous one has finished processing. To have webpack process them in parallel, you can use a third-party solution like [parallel-webpack](https://www.npmjs.com/package/parallel-webpack).
+## Compiler Instance
+If you don’t pass the `webpack` runner function a callback, it will return a
+webpack `Compiler` instance. This instance can be used to manually trigger the
+webpack runner or have it build and watch for changes, much like the
+[CLI](/api/cli/). The `Compiler` instance provides the following methods:
-## Compiler Instance
+- `.run(callback)`
+- `.watch(watchOptions, handler)`
+
+Typically, only one master `Compiler` instance is created, although child
+compilers can be created in order to delegate specific tasks. The `Compiler` is
+ultimately just a function which performs bare minimum functionality to keep a
+lifecycle running. It delegates all the loading, bundling, and writing work to
+registered plugins.
-If you don’t pass the `webpack` runner function a callback, it will return a webpack `Compiler` instance. This instance can be used to manually trigger the webpack runner or have it build and watch for changes. Much like the [CLI](/api/cli/) Api. The `Compiler` instance provides the following methods:
+The `hooks` property on a `Compiler` instance is used to register a plugin to
+any hook event in the `Compiler`'s lifecycle. The [`WebpackOptionsDefaulter`]
+(https://github.com/webpack/webpack/blob/master/lib/WebpackOptionsDefaulter.js)
+and [`WebpackOptionsApply`](https://github.com/webpack/webpack/blob/master/lib/WebpackOptionsApply.js)
+utilities are used by webpack to configure its `Compiler` instance with all the
+built-in plugins.
-* `.run(callback)`
-* `.watch(watchOptions, handler)`
+The `run` method is then used to kickstart all compilation work. Upon
+completion, the given `callback` function is executed. The final logging of
+stats and errors should be done in this `callback` function.
-W> The API only supports a single concurrent compilation at a time. When using `run`, wait for it to finish before calling `run` or `watch` again. When using `watch`, call `close` and wait for it to finish before calling `run` or `watch` again. Concurrent compilations will corrupt the output files.
+W> The API only supports a single concurrent compilation at a time. When using
+`run`, wait for it to finish before calling `run` or `watch` again. When using
+`watch`, call `close` and wait for it to finish before calling `run` or `watch`
+again. Concurrent compilations will corrupt the output files.
## Run
-Calling the `run` method on the `Compiler` instance is much like the quick run method mentioned above:
+Calling the `run` method on the `Compiler` instance is much like the quick run
+method mentioned above:
``` js-with-links
const webpack = require("webpack");
@@ -92,13 +105,15 @@ compiler.run((err, [stats](#stats-object)) => {
## Watching
-Calling the `watch` method, triggers the webpack runner, but then watches for changes (much like CLI: `webpack --watch`), as soon as webpack detects a change, runs again. Returns an instance of `Watching`.
+Calling the `watch` method, triggers the webpack runner, but then watches for
+changes (much like CLI: `webpack --watch`), as soon as webpack detects a
+change, runs again. Returns an instance of `Watching`.
-``` js-with-links
+``` js
watch(watchOptions, callback)
```
-``` js-with-links-with-details
+``` js-with-links
const webpack = require("webpack");
const compiler = webpack({
@@ -106,24 +121,28 @@ const compiler = webpack({
});
const watching = compiler.watch({
- /* [watchOptions](/configuration/watch/#watchoptions) */
+ // Example [watchOptions](/configuration/watch/#watchoptions)
aggregateTimeout: 300,
poll: undefined
-