Pug 3.x cache invalidation for included partials after template edits

Cache Invalidation Behavior

In Pug 3.0.2+, the cache invalidation logic remains tied exclusively to the mtime (modification time) of the entry template. When cache: true is enabled, Pug checks whether the entry file has changed; however, it does not recursively track the modification times of files referenced via include or extends. Consequently, edits to partials will not trigger a recompilation of the parent template in production mode. This is the likely explanation for the divergence you see between development and production, though it is worth verifying against your exact Pug version, since earlier 3.x releases may differ.

Internal Cache Access

The pug.cache export was removed in Pug 3.x. The internal LRU cache is no longer exposed via a public API, so there is no built-in method to programmatically inspect or clear the default internal cache without restarting the Node.js process.

Resolution: Implementing a Custom Cache Object

To maintain production-level performance while gaining control over partial invalidation, replace the default boolean cache setting with a custom cache object. Pug's compileFile and renderFile accept a cache option that can be a Map or any object implementing a similar get/set interface, as described in the Pug 3.x API reference.

Implementation Steps:

1. Initialize a shared cache: Create a Map or a bounded LRU cache instance shared across all rendering calls.
2. Pass the cache to the renderer: Instead of cache: true, pass the instance to pug.renderFile() or your Express view settings.
3. Manual invalidation: When a partial is updated (for example, via a file watcher in a test suite), clear the cache map or delete the specific key associated with the entry template.

const pug = require('pug');
const customCache = new Map();

// Render using the custom cache
const html = pug.renderFile('views/index.pug', {
  cache: customCache,
  basedir: 'views/'
});

// To force recompilation of partials, clear the cache
function invalidateTemplates() {
  customCache.clear();
}

Verification and Constraints

To verify this in a test suite, render a page containing a partial, modify the partial file on disk, and render again — the output should remain stale. After calling customCache.clear(), the subsequent render should reflect the changes. You can also instrument the cache object with logging on get, set, and delete to confirm entries are stored and removed as intended.

Caveats: All parts of the application must share the same cache instance, or stale entries will persist. An unbounded Map can grow memory usage, so prefer a bounded LRU in long-running processes. If using Express, note that app.set('view cache', true) manages its own layer, so integration tests should confirm the custom cache is actually consulted. The basedir option also matters: different basedir values create different cache keys for the same file, which can mask stale-output bugs in test configurations.

One diagnostic detail that changes the recommendation: are you rendering via Express's app.render()/res.render(), or calling pug.renderFile() directly? With direct calls you control the options object yourself; with Express you must coordinate with its view engine settings, which changes where the custom cache is injected.