Enable Webpack 5 Persistent Filesystem Cache for Faster Incremental Builds

Problem: incremental dev builds waste time reprocessing unchanged modules

With Webpack 5, the first build of a large app can be slow and subsequent builds during development often repeat work that has not changed. The useful takeaway is that the built-in persistent filesystem cache can store module metadata, dependencies and build artifacts on disk and reuse them across runs, reducing incremental build time without changing source code.

Desired outcome

A repeatable development build where the second run with unchanged sources reuses cached modules, and a small source edit rebuilds only affected chunks. Cache invalidation should happen automatically when webpack configuration or loader options change.

Prerequisites

• Webpack 5 installed in the project. Persistent cache is a Webpack 5 feature.
• output.path is set to an absolute directory. Filesystem cache requires a deterministic output location.
• Write permission for the chosen cache directory, typically node_modules/.cache or a path inside the project.
• Stable module identifiers. Avoid timestamp-based filenames and non-deterministic plugins during validation.

Configuration

Add a cache block to webpack.config.js. Run the commands in the project root where package.json lives.

const path = require('path');
module.exports = {
  mode: 'development',
  output: {
    path: path.resolve(__dirname, 'dist')
  },
  cache: {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename]
    }
  }
};

cache.type: 'filesystem' enables persistent on-disk caching. cache.buildDependencies.config ensures the cache is invalidated when the config file changes. You can also set cache.cacheDirectory to a custom absolute path if you do not want the default under node_modules/.cache.

For environment-specific control, disable cache in CI or production where clean builds are preferred:

cache: process.env.NODE_ENV === 'development' ? { type: 'filesystem' } : false

Verification

Run webpack twice with the same sources and inspect stats.

npm run build

Expected checks after first run:

• A cache directory is created under the configured location. Inspect it for files after the first build.
• Webpack stats should report cache usage. Enable stats output to see cache related messages.

Run the build again without changing sources. Expected checks:

• Second run should report cache hits for modules that did not change.
• Overall build time should be lower than the first run.

Modify a single source file and rebuild. Expected checks:

• Only the affected module and its dependents rebuild.
• Build time drops compared to a full rebuild.

Remove the cache directory and rebuild to confirm a clean build still succeeds:

rm -rf node_modules/.cache/webpack

Then run the build again. A successful clean build confirms the configuration is not dependent on stale cache.

Limitations and risks

Cache invalidation is sensitive to webpack version upgrades and changes in loader options. A stale cache can cause incorrect bundles. Treat cache as build state.

Non-deterministic plugins or loaders that embed timestamps or random values defeat cache hits.

On shared CI machines, use isolated cache directories per branch to avoid cross-contamination. Do not share a single cache across different webpack versions.

Recovery options

If builds produce unexpected output after config or loader changes:

1. Clear the persistent cache by removing the cache directory. This forces a full rebuild with fresh metadata.
2. Temporarily set cache to false to confirm the issue is cache related.
3. Re-enable cache after verifying the build is correct.

Rollback is safe because cache is additive. Removing it only costs an extra build, it does not modify source.

Practical check

Keep a simple manual check in your workflow: first build, second build with no changes, edit one file. Compare the reported times and the number of modules rebuilt. If the second build does not reuse cached modules, review module identifiers, loader options and plugins for non-determinism.