Webpack Module Graph and Plugin System

The Bundler That Started It All

Before webpack, JavaScript had no native module system in browsers. You'd slap a bunch of <script> tags on the page in the right order, pray nothing collided, and call it a day. Webpack changed everything by treating your entire application as a dependency graph — starting from a single entry point and recursively resolving every import and require until it maps out the full tree.

Here's the thing most people miss about webpack: it's not just a "bundler." It's a compiler with a plugin architecture. The bundling part is almost secondary to the extensible pipeline that makes webpack capable of handling CSS, images, fonts, WASM, and literally anything else through its loader and plugin system.

Entry Points: Where the Graph Begins

Every webpack build starts with one or more entry points. An entry point is the file webpack reads first — the root of your dependency graph.

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

From ./src/index.js, webpack follows every import and require statement recursively. If index.js imports App.js, which imports Header.js and utils.js, which imports lodash — webpack discovers all four modules and their relationship to each other.

You can have multiple entry points for multi-page apps:

module.exports = {
  entry: {
    home: './src/pages/home.js',
    dashboard: './src/pages/dashboard.js',
    settings: './src/pages/settings.js',
  },
};

Each entry creates a separate dependency graph. Shared modules between entries get deduplicated automatically (more on that in chunk splitting).

Module Graph Construction

This is where it gets interesting. Webpack's core job is building a module graph — a directed graph where each node is a module and each edge is an import/require relationship.

Module Graph for a typical app:

  entry: index.js
       │
       ├── App.js
       │    ├── Header.js
       │    │    └── logo.svg (via file-loader)
       │    ├── Sidebar.js
       │    │    └── nav-items.json
       │    └── styles.css (via css-loader)
       │
       ├── utils/format.js
       │    └── date-fns/format
       │
       └── api/client.js
            └── axios

The Resolution Algorithm

When webpack encounters import { format } from 'date-fns', it needs to find the actual file. The resolution algorithm follows these steps:

1. Check if it's a relative path (./, ../) — resolve relative to the importing file
2. Check if it's a module — look in node_modules directories, walking up the directory tree
3. Check the package's exports field (Node.js subpath exports), then module field (ESM entry), then main field (CJS entry)
4. Apply resolve.extensions — try .js, .jsx, .ts, .tsx, etc.
5. Apply resolve.alias — replace configured path prefixes

module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
    },
  },
};

Loaders: The Transform Pipeline

Webpack only understands JavaScript and JSON natively. Everything else — TypeScript, CSS, images, SVG, MDX — needs a loader to transform it into something webpack can process.

Loaders are functions that take source content as input and return transformed content:

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.svg$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};

Loader Chaining

Here's the key insight: loaders are chained right to left (or bottom to top in the array). Each loader receives the output of the previous one:

{
  test: /\.css$/,
  use: ['style-loader', 'css-loader', 'postcss-loader'],
}

Execution order:
  postcss-loader  →  Takes raw CSS, runs PostCSS transforms (autoprefixer, etc.)
       ↓
  css-loader      →  Resolves @import and url(), converts to JS module
       ↓
  style-loader    →  Injects CSS into the DOM via a <style> tag at runtime

The right-to-left order trips up everyone at first. Think of it like function composition: style(css(postcss(source))). The innermost function runs first.

Plugins: Tapping Into Compiler Hooks

Loaders transform individual files. Plugins operate on the entire compilation — they can modify the build output, inject environment variables, generate additional files, optimize chunks, and much more.

Under the hood, webpack's compiler emits events at every stage of the build process using a library called Tapable. Plugins "tap" into these hooks to do their work:

const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new HtmlWebpackPlugin({ template: './src/index.html' }),
    new MiniCssExtractPlugin({ filename: '[name].[contenthash].css' }),
    new BundleAnalyzerPlugin({ analyzerMode: 'static' }),
  ],
};

The Compiler Hook Lifecycle

The compiler goes through a defined sequence of hooks during a build. Here's the condensed version:

Writing a Simple Plugin

A webpack plugin is an object with an apply method that receives the compiler:

class BuildTimerPlugin {
  apply(compiler) {
    let startTime;

    compiler.hooks.compile.tap('BuildTimerPlugin', () => {
      startTime = Date.now();
    });

    compiler.hooks.done.tap('BuildTimerPlugin', (stats) => {
      const duration = Date.now() - startTime;
      console.log(`Build completed in ${duration}ms`);
    });
  }
}

The tap method registers a synchronous handler. For async operations, you'd use tapAsync (callback-based) or tapPromise (Promise-based).

Chunk Splitting

Webpack groups modules into chunks — the actual files that get emitted. By default, each entry point creates one chunk. But smart chunk splitting can dramatically improve loading performance.

Default Behavior (Production Mode)

Webpack 5's optimization.splitChunks is enabled by default in production mode:

module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      minSize: 20000,
      minChunks: 1,
      maxAsyncRequests: 30,
      maxInitialRequests: 30,
      cacheGroups: {
        vendors: {
          test: /[\\/]node_modules[\\/]/,
          priority: -10,
          reuseExistingChunk: true,
        },
        default: {
          minChunks: 2,
          priority: -20,
          reuseExistingChunk: true,
        },
      },
    },
  },
};

This creates three types of chunks:

1. Entry chunks — your application code per entry point
2. Vendor chunks — third-party code from node_modules
3. Common chunks — modules shared between 2+ entry points

Build output with splitChunks:
  main.js           → 45KB  (your app code)
  vendors-react.js  → 130KB (react + react-dom)
  vendors-lodash.js → 72KB  (lodash)
  commons.js        → 12KB  (shared utilities)

The benefit: vendor chunks change rarely (you don't update React every day), so browsers cache them long-term. Only your application code chunk invalidates on each deploy.

Hot Module Replacement (HMR) Internals

HMR is the feature that lets you edit code and see changes instantly without a full page reload. Understanding how it works demystifies a lot of "why is HMR not working?" debugging.

When HMR fails (you see a full page reload instead), it usually means the update couldn't be applied in-place — either no module.hot.accept() handler exists in the module chain, or the update caused an error. React Fast Refresh handles this automatically for React components, but non-component modules (utilities, constants) may need manual handling.

Output Configuration

The output configuration controls how and where webpack writes the final files:

const path = require('path');

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
    clean: true,
    publicPath: '/static/',
  },
};

Key placeholders:

• [name] — the chunk name (from entry config or dynamic import comment)
• [contenthash] — hash of the chunk's content (changes only when content changes)
• [chunkhash] — hash of the entire chunk (less granular than contenthash)

Always use [contenthash] for long-term caching. When a file's content doesn't change between builds, its hash stays the same, and browsers use the cached version.