contenthash vs chunkhash: handling stale cache when modules move between chunks

Direct Answer

Webpack does not automatically delete previously emitted chunk files when a module moves to a different chunk. Stale assets remain in the output directory until you explicitly clean it. The choice between [contenthash] and [chunkhash] does not by itself create or prevent orphaned-file requests; orphaned files are only served if something (old HTML, a service-worker precache manifest, a hard-coded URL, or a browser cache) still requests the old filename.

Why Stale Files Persist

Each Webpack compilation emits only the assets that exist in the current module graph. When splitChunks moves a module from an entry-specific chunk into a shared chunk, the old chunk is still emitted (now without that module) and the new shared chunk is emitted. Both receive new hashes because their contents changed. The previous build's files, however, are left untouched on disk. HtmlWebpackPlugin rewrites the HTML to point at the new hashed filenames, but it never deletes the old ones.

How to Clean Stale Assets

Webpack 5 (recommended)

// webpack.config.js
module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    clean: true          // removes output.path before each emit
  }
};

The clean option deletes the entire output.path directory before writing new assets. Ensure that directory contains only build output.

Webpack 4 or when output.clean is unavailable

// Option A: clean-webpack-plugin
const { CleanWebpackPlugin } = require('clean-webpack-plugin');
module.exports = {
  plugins: [new CleanWebpackPlugin()]
};

# Option B: pre-build script (cross-platform)
npx rimraf dist
# or
rm -rf dist

contenthash vs chunkhash: Practical Difference

Use [contenthash] for finer-grained invalidation (e.g., extracted CSS stays cached when only JS changes). Use [chunkhash] if you want a single version token per logical chunk. Neither eliminates the need to clean dist.

Verification Checklist

1. Confirm Webpack version: npx webpack --version (output.clean requires Webpack 5.20+).
2. Move a module between an entry chunk and a splitChunks cache group, build twice, and list dist/ — you should see only the latest hashed files if cleaning works.
3. Open the generated HTML and verify every <script>/<link> points to a file that currently exists in dist/.
4. Check browser DevTools Network tab or server logs for requests to filenames that no longer exist.

One Diagnostic Detail

What Webpack version are you running, and does your deployment pipeline already include a dist cleanup step (e.g., clean: true, clean-webpack-plugin, or a CI rm -rf)? The answer determines whether you need to add configuration or simply verify the existing cleanup runs on every build.