Compiler

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

// 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

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". This is typically used in 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 or the 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.

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
Event name
entry-option
Reason
-
Params
-
Type
bailResult
Event name
after-plugins
Reason
After setting up initial set of plugins
Params
compiler
Type
sync
Event name
after-resolvers
Reason
After setting up the resolvers
Params
compiler
Type
sync
Event name
environment
Reason
-
Params
-
Type
sync
Event name
after-environment
Reason
Environment setup complete
Params
-
Type
sync
Event name
before-run
Reason
compiler.run() starts
Params
compiler
Type
async
Event name
run
Reason
Before reading records
Params
compiler
Type
async
Event name
watch-run
Reason
Before starting compilation after watch
Params
compiler
Type
async
Event name
normal-module-factory
Reason
After creating a NormalModuleFactory
Params
normalModuleFactory
Type
sync
Event name
context-module-factory
Reason
After creating a ContextModuleFactory
Params
contextModuleFactory
Type
sync
Event name
before-compile
Reason
Compilation parameters created
Params
compilationParams
Type
async
Event name
compile
Reason
Before creating new compilation
Params
compilationParams
Type
sync
Event name
this-compilation
Reason
Before emitting compilation event
Params
compilation
Type
sync
Event name
compilation
Reason
Compilation creation completed
Params
compilation
Type
sync
Event name
make
Reason
-
Params
compilation
Type
parallel
Event name
after-compile
Reason
-
Params
compilation
Type
async
Event name
should-emit
Reason
Can return true/false at this point
Params
compilation
Type
bailResult
Event name
need-additional-pass
Reason
-
Params
-
Type
bailResult
Event name
emit
Reason
Before emitting assets to output dir
Params
compilation
Type
async
Event name
after-emit
Reason
After emitting assets to output dir
Params
compilation
Type
async
Event name
done
Reason
Completion of compile
Params
stats
Type
sync
Event name
failed
Reason
Failure of compile
Params
error
Type
sync
Event name
invalid
Reason
After invalidating a watch compile
Params
fileName, changeTime
Type
sync
Event name
watch-close
Reason
After stopping a watch compile
Params
-
Type
sync

Usage

Here's an example of an asynchronous emit event handler:

compiler.plugin("emit", function(compilation, callback) {
  // Do something async...
  setTimeout(function() {
    console.log("Done with async work...");
    callback();
  }, 1000);
});