Under The Hood

This section describes webpack internals and can be useful for plugin developers

The bundling is a function that takes some files and emits others.

But between input and output, it also has modules, entry points, chunks, chunk groups, and many other intermediate parts.

The main parts

Every file used in your project is a Module

./index.js

import app from './app.js';

./app.js

export default 'the app';

By using each other, the modules form a graph (ModuleGraph).

During the bundling process, modules are combined into chunks. Chunks combine into chunk groups and form a graph (ChunkGraph) interconnected through modules. When you describe an entry point - under the hood, you create a chunk group with one chunk.

./webpack.config.js

module.exports = {
  entry: './index.js',
};

One chunk group with the main name created (main is the default name for an entry point). This chunk group contains ./index.js module. As the parser handles imports inside ./index.js new modules are added into this chunk.

Another example:

./webpack.config.js

module.exports = {
  entry: {
    home: './home.js',
    about: './about.js',
  },
};

Two chunk groups with names home and about are created. Each of them has a chunk with a module - ./home.js for home and ./about.js for about

There might be more than one chunk in a chunk group. For example SplitChunksPlugin splits a chunk into one or more chunks.

Chunks

Chunks come in two forms:

• initial is the main chunk for the entry point. This chunk contains all the modules and their dependencies that you specify for an entry point.
• non-initial is a chunk that may be lazy-loaded. It may appear when dynamic import or SplitChunksPlugin is being used.

Each chunk has a corresponding asset. The assets are the output files - the result of bundling.

webpack.config.js

module.exports = {
  entry: './src/index.jsx',
};

./src/index.jsx

import React from 'react';
import ReactDOM from 'react-dom';

import('./app.jsx').then((App) => {
  ReactDOM.render(<App />, root);
});

Initial chunk with name main is created. It contains:

• ./src/index.jsx
• react
• react-dom

and all their dependencies, except ./app.jsx

Non-initial chunk for ./app.jsx is created as this module is imported dynamically.

Output:

• /dist/main.js - an initial chunk
• /dist/394.js - non-initial chunk

By default, there is no name for non-initial chunks so that a unique ID is used instead of a name. When using dynamic import we may specify a chunk name explicitly by using a "magic" comment:

import(
  /* webpackChunkName: "app" */
  './app.jsx'
).then((App) => {
  ReactDOM.render(<App />, root);
});

Output:

• /dist/main.js - an initial chunk
• /dist/app.js - non-initial chunk

Output

The names of the output files are affected by the two fields in the config:

• output.filename - for initial chunk files
• output.chunkFilename - for non-initial chunk files
• In some cases chunks are used initial and non-initial. In those cases output.filename is used.

A few placeholders are available in these fields. Most often:

• [id] - chunk id (e.g. [id].js -> 485.js)
• [name] - chunk name (e.g. [name].js -> app.js). If a chunk has no name, then its id will be used
• [contenthash] - md4-hash of the output file content (e.g. [contenthash].js -> 4ea6ff1de66c537eb9b2.js)