When does Jest's transform cache serve stale output from a custom transformer that reads external files?

Answer

Jest’s on‑disk transform cache will serve stale output whenever a custom transformer reads an external file (e.g., a shared config) but does not include that file’s content in the cache key. If the external file changes and the transformer’s getCacheKey method is not implemented (or does not hash the file), the cache key remains unchanged, so Jest returns the previously transformed result.

Confirmed facts

• The default transform cache key in Jest 29 incorporates the source file’s content hash, the transformer’s implementation, the Jest version, and selected parts of the Jest configuration.
• Files accessed inside a transformer’s process method are not automatically hashed into the default key.
• Providing a getCacheKey method that returns a hash of any external dependency is the documented way to extend the cache key and force a re‑transform when that dependency changes.
• The haste‑map cache is a separate layer that tracks file metadata and module resolution paths; it does not store transformed code.
• Watchman speeds up the file‑system crawling used by haste‑map but does not alter the transform cache key or automatically invalidate stale transform entries.

Likely explanation

When you edit only the external config file, the source file’s hash, the transformer code, and the Jest config stay the same. Because the default key ignores the config file, the cache entry remains valid and Jest returns the old transformed output. This manifests as stale inlined values until the cache is bust­ed (e.g., by jest --clearCache) or the key is changed via getCacheKey.

Steps to resolve

1. Implement getCacheKey in your custom transformer:

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

module.exports = {
  process(src, filepath, config, options) {
    // your inlining logic that reads e.g. path.join(filepath, '..', 'shared.json')
    return transformed;
  },
  getCacheKey(fileData, fsStr, options, instrument) {
    // hash the transformer source (fileData) as Jest does by default
    const base = crypto.createHash('md5').update(fileData, 'utf8').digest('hex');
    // hash the external config file you read
    const configPath = path.resolve(options.rootDir, 'shared.json');
    const configHash = crypto.createHash('md5')
      .update(fsStr.readFileSync(configPath, 'utf8'), 'utf8')
      .digest('hex');
    // combine with Jest version and config if desired
    return `${base}-${configHash}-${options.jestVersion}`;
  }
};

2. Verify locally: change the external file, run Jest again, and confirm the transformation re‑runs without needing --clearCache.
3. If you prefer not to modify the transformer, add a CI step that runs jest --clearCache before each build; this clears both transform and haste‑map caches.

Interaction with haste‑map and Watchman

Editing or copying files into a CI workspace can leave the haste‑map with stale module‑resolution entries, causing Jest to look for a module at the old path. This is independent of the transform cache. Enabling Watchman (or setting watchman: true in Jest config) makes the haste‑map update faster, but it does not fix stale transform output caused by external file changes; you still need a proper getCacheKey or a cache clear.

Missing diagnostic detail

Are you observing the stale output only when running Jest in watch mode, or also in a fresh CI run? Knowing this will determine whether enabling Watchman (for haste‑map freshness) is sufficient or whether a cache‑clear step is required.