Demystifying Webpack: Inside the Build Process and Core Concepts

Introduction

Currently, almost every business development project uses Webpack. As a powerful module loader and bundler, it offers a painless workflow after a few configuration files and loaders, but its overall process and philosophy remain opaque to many developers.

Preparation

1. Configure webpack-webstorm-debugger-script in WebStorm

Before diving in, you need to be able to debug the entire Webpack flow. Place webstorm-debugger.js in the same directory as webpack.config.js, then you can directly debug the script.

2. webpack.config.js Configuration

A typical webpack.config.js looks like this:

var path = require('path');
var node_modules = path.resolve(__dirname, 'node_modules');
var pathToReact = path.resolve(node_modules, 'react/dist/react.min.js');
module.exports = {
  entry: {
    bundle: [
      'webpack/hot/dev-server',
      'webpack-dev-server/client?http://localhost:8080',
      path.resolve(__dirname, 'app/app.js')
    ]
  },
  resolve: { alias: { 'react': pathToReact } },
  output: { path: path.resolve(__dirname, 'build'), filename: '[name].js' },
  module: {
    loaders: [{ test: /\.js$/, loader: 'babel', query: { presets: ['es2015', 'react'] } }],
    noParse: [pathToReact]
  },
  plugins: [new webpack.HotModuleReplacementPlugin()]
};

Key concepts introduced:

loader : transforms resources into modules; loaders can be chained.

chunk : the result of code splitting, representing a loadable piece containing modules.

Relationship between modules and chunks is illustrated below:

3. Process Overview

Save the following overall flow diagram for reference:

Shell and Config Parsing

When you run webpack from the command line, the OS executes ./node_modules/.bin/webpack, which in turn calls ./node_modules/webpack/bin/webpack.js with the supplied arguments (e.g., -p, -w).

Inside webpack.js, the optimist library merges the user’s webpack.config.js with command‑line arguments into an options object.

1. Optimist

Optimist parses CLI arguments similarly to commander:

var optimist = require("optimist");
optimist
  .boolean("json").alias("json", "j").describe("json")
  .boolean("colors").alias("colors", "c").describe("colors")
  .boolean("watch").alias("watch", "w").describe("watch");

Resulting argv looks like:

// webpack --hot -w
{
  hot: true,
  profile: false,
  watch: true,
  ...
}

2. Config Merging and Plugin Loading

Webpack copies configuration items from webpack.config.js into options and loads plugins defined there. Then optimist.argv is passed to ./node_modules/webpack/bin/convert-argv.js, which decides which plugins to activate based on CLI flags.

ifBooleanArg("hot", function () {
  ensureArray(options, "plugins");
  var HotModuleReplacementPlugin = require("../lib/HotModuleReplacementPlugin");
  options.plugins.push(new HotModuleReplacementPlugin());
});
...return options;

Compilation and Build Flow

After loading configuration and CLI plugins, Webpack creates a Compiler instance. The run method triggers a series of events: compile – start compilation make – analyze entry points and build module graph build-module – build each module after-compile – finish building seal – seal compilation results emit – write chunks to output files after-emit – finalization

1. Core Object: Compilation

The Compilation object orchestrates the entire bundling process, exposing methods such as addEntry(), _addModuleChain(), buildModule(), seal(), and createChunkAssets(). It also stores all modules, chunks, and assets.

2. Compilation and Build Main Flow

During make, Compilation.addEntry locates the entry file from options.entry, then calls _addModuleChain to create and build modules.

Building a module involves three steps:

Apply loaders to transform the source.

Parse the transformed source with acorn to generate an AST.

Traverse the AST to discover and add dependencies, recursively processing them.

Example of the module‑chain process:

Compilation.prototype._addModuleChain = function process(context, dependency, onModule, callback) {
  var moduleFactory = this.dependencyFactories.get(dependency.constructor);
  moduleFactory.create(context, dependency, function (err, module) {
    var result = this.addModule(module);
    this.buildModule(module, function (err) {
      // build module, add dependencies
    }.bind(this));
  }.bind(this));
};

3. Build Details

Webpack defines several module subclasses ( NormalModule, MultiModule, ContextModule, DelegatedModule) that all implement a build() method. The NormalModule.build method performs timestamping, optional parsing bypass, AST generation, and error handling.

NormalModule.prototype.build = function (options, compilation, resolver, fs, callback) {
  this.buildTimestamp = new Date().getTime();
  this.built = true;
  this.doBuild(options, compilation, resolver, fs, function (err) {
    if (options.module && options.module.noParse) { /* skip parsing */ }
    try {
      this.parser.parse(this._source.source(), { ecmaVersion: 6, sourceType: "module" });
    } catch (e) {
      return callback(new ModuleParseError(this, source, e));
    }
    return callback();
  }.bind(this));
};

Packaging Output

After all modules and their dependencies are built, Webpack listens for the seal event, allowing plugins to finalize assets. It sorts chunks, creates assets via createChunkAssets, and finally writes files using emitAssets according to the output configuration.

Compilation.prototype.seal = function (callback) {
  this.applyPlugins("seal");
  this.preparedChunks.sort(function (a, b) { return a.name < b.name ? -1 : a.name > b.name ? 1 : 0; });
  this.preparedChunks.forEach(function (preparedChunk) {
    var module = preparedChunk.module;
    var chunk = this.addChunk(preparedChunk.name, module);
    chunk.initial = chunk.entry = true;
    chunk.addModule(module);
    module.addChunk(chunk);
  }, this);
  this.applyPluginsAsync("optimize-tree", this.chunks, this.modules, function (err) {
    if (err) return callback(err);
    this.createChunkAssets();
    // further plugin hooks
    callback();
  }.bind(this));
};

1. Generating Final Assets

During sealing, Webpack selects a template based on whether a chunk is an entry or async chunk. It then renders the chunk using MainTemplate or ChunkTemplate, which ultimately calls module.source() to replace require() calls and produce the final code.

MainTemplate.prototype.requireFn = "__webpack_require__";
MainTemplate.prototype.render = function (hash, chunk, moduleTemplate, dependencyTemplates) {
  var buf = [];
  buf.push("function " + this.requireFn + "(moduleId) {");
  buf.push(this.indent(this.applyPluginsWaterfall("require", "", chunk, hash)));
  buf.push("}");
  // further wrapping logic
};

2. Output

The final step calls Compiler.emitAssets(), which writes the generated files to the path defined in output. Custom plugins can hook into the emit event to further process results.

Conclusion

The overall Webpack workflow hinges on the Compilation and Module objects, but its philosophy extends beyond simple bundling. Webpack is essentially a collection of plugins orchestrated by tapable. Understanding these internals enables developers to write custom plugins for performance optimization or bundle size reduction.