Speeding Up Webpack Rebuilds with the Persistent Filesystem Cache

When a project grows, even a small change can trigger a noticeable pause while Webpack re‑runs loaders and resolves modules. The delay adds up during development, especially when you rely on fast feedback loops. Enabling Webpack 5’s persistent filesystem cache stores the results of expensive steps on disk, so subsequent builds can reuse them and start faster.

How the persistent cache speeds up rebuilds

Webpack 5 introduced a stable cache that writes compilation artifacts to the file system instead of keeping them only in memory. When you run webpack a second time, the compiler reads the stored snapshot of each module, skips re‑executing loaders whose inputs have not changed, and only rebuilds the parts that are truly affected. This can shave seconds or minutes off incremental builds in large codebases that use heavy loaders such as babel-loader or ts-loader.

Configuration basics and invalidation

The simplest way to turn the feature on is:

// webpack.config.js
module.exports = {
  cache: {
    type: 'filesystem'
  },
  // "…rest of config"
};

By default Webpack writes the cache to node_modules/.cache/webpack relative to the project root. The cache is automatically invalidated when Webpack detects changes to:

• the Webpack configuration file itself
• any loader or plugin specified in the config
• dependencies listed in package.json (via their resolved paths)

If you have additional files that influence the build—such as custom configuration files, environment files, or scripts that generate part of the config—you should declare them explicitly so the cache knows when to bust:

module.exports = {
  cache: {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename, './custom-webpack.settings.js']
    },
    version: '1.0'   // optional, bump when you make breaking changes
  }
};

The buildDependencies option tells Webpack to treat the listed files as part of the cache key; editing any of them forces a full cache miss for the next build.

Worked example: measuring the gain

1. Start with a fresh checkout (or delete node_modules/.cache/webpack) to ensure a cold start.
2. Run the build and note the time: time webpack --mode development (or use console.time in a script).
3. Run the same command a second time without changing any source files. The second run should finish noticeably faster because most modules are restored from the cache.
4. Inspect the cache directory: ls -la node_modules/.cache/webpack. You will see files with hashes that correspond to modules and chunks.
5. Now edit a file that you added to buildDependencies.config (for example, touch custom-webpack.settings.js). Run the build again. This time Webpack should treat the cache as invalid and re‑process modules, giving you a build time similar to the first cold run.

These steps let you verify that the cache is being written, read, and invalidated as expected.

Trade‑offs and CI strategy

While the filesystem cache can dramatically improve local developer experience, it introduces a few considerations:

• Disk usage. The cache grows with the number of modules and the size of their compiled output. On very large projects the node_modules/.cache/webpack folder can occupy several hundred megabytes. You can control growth with the maxAge option (e.g., maxAge: 10 * 24 * 60 * 60 * 1000 to keep entries for ten days) or by periodically clearing the folder.
• CI caching. In continuous‑integration pipelines you can restore the cache directory between jobs to avoid paying the cold‑start cost on every run. Most CI services allow you to cache node_modules; extending that to node_modules/.cache yields additional savings. Remember to invalidate the cached directory when you change dependencies or the Webpack configuration—otherwise you risk using stale build artifacts.
• Stale cache bugs. If a custom loader reads a file without declaring it as a dependency, Webpack may incorrectly consider the module up‑to‑date. The symptom is a build that appears to succeed but uses outdated code. Deleting the cache folder is the standard first step when you encounter inexplicable build errors.

Monitoring the cache size and setting a reasonable maxAge helps keep the trade‑off in favor of faster builds without uncontrolled disk growth.

To start using the persistent filesystem cache today, add the cache field to your Webpack configuration, verify the speedup with a local two‑run test, and extend your CI cache definition to include node_modules/.cache. With those steps in place you should see quicker rebuilds and a more responsive development loop.