babel-loader cacheDirectory does not invalidate on Babel config changes

Solving Stale Babel Cache

To automatically invalidate the babel-loader cache when your Babel configuration changes, the recommended approach is to implement a custom cacheIdentifier. By default, babel-loader tracks the version of the loader and the source file content, but it may not consistently detect changes in external configuration files like babel.config.js or .babelrc.

Implementing a Dynamic cacheIdentifier

The cacheIdentifier option allows you to provide a string or a function that returns a string. If this string changes, the loader treats the entire cache as invalid. The most effective way to bind this to your configuration is to hash the contents of your Babel config file.

const fs = require('fs');
const crypto = require('crypto');

// Generate a hash of the babel config file
const babelConfigHash = crypto
  .createHash('md5')
  .update(fs.readFileSync('./babel.config.js', 'utf8'))
  .digest('hex');

module.exports = {
  module: {
    rules: [{
      test: /\.js$/,
      loader: 'babel-loader',
      options: {
        cacheDirectory: true,
        // The cache is invalidated whenever the config hash changes
        cacheIdentifier: `babel-config-${babelConfigHash}`
      }
    }]
  }
};

Analysis of Cache Behavior

Likely Explanation: babel-loader prioritizes build speed by hashing the source file and the loader version. While some versions attempt to track the config, external dependencies or complex babel.config.js logic (e.g., environment-based conditionals) can bypass this detection, leading to stale artifacts.

Confirmed Facts:

• cacheDirectory: true stores results in node_modules/.cache/babel-loader.
• Manual deletion of this directory always forces a full re-compile.
• The cacheIdentifier acts as a global version key for the cache.

Practical Considerations

• Manual Clearing: Teams should avoid relying on manual cache clearing in CI/CD pipelines; instead, use a unique cacheIdentifier based on the commit hash or config hash.
• Watch Mode/Dev Server: Using a static hash generated at the start of the Webpack process (as shown above) will not detect changes to the config file during a live session. You would still need to restart the dev server for the new hash to be calculated and the cache to invalidate.

Verification Steps

1. Enable cacheDirectory: true and run a build.
2. Modify a plugin or preset in your Babel config.
3. Run the build again; if the output is unchanged, the cache is stale.
4. Apply the cacheIdentifier logic and verify the build output updates after a server restart.

Diagnostic Detail: Are you using a .babelrc (JSON) or a babel.config.js (JavaScript) file? If using a JS file with dynamic logic, a simple file hash may not be sufficient if the logic depends on external environment variables.