Pug cache continues to serve stale templates after file edits

Direct answer

Pug’s internal cache does not watch the filesystem; when cache: true (or Express view cache) is enabled, a compiled function is stored in require('pug').cache keyed by the resolved file path and reused until the entry is removed or the Node process restarts. Editing a template file therefore yields stale output until the cache is cleared.

How compileDebug interacts with caching

Across all major releases (pre‑3.0 and 3.x), compileDebug: true only adds source‑map / line‑number instrumentation to the compiled function. It does **not** disable caching, nor does it change the key used in pug.cache. The flag is orthogonal: you can have both cache: true and compileDebug: true, and the debug‑enabled function will be cached just like a production build.

Steps for automatic invalidation in a single‑process setup

1. Disable caching during development: app.set('view cache', false) (Express) or pass {cache: false} to pug.renderFile.
2. For a production‑like hot‑reload workflow, add a file‑watcher that deletes the cache entry when a .pug file changes:

const chokidar = require('chokidar');
const pug = require('pug');
const path = require('path');

chokidar.watch('views/**/*.pug', { awaitWriteFinish: true })
  .on('change', filePath => {
    const resolved = path.resolve(filePath);
    delete pug.cache[resolved];
    console.log(`Cleared Pug cache for ${resolved}`);
  });

After the watcher runs, the next renderFile call will recompile the edited template, eliminating stale output.

Multi‑process / clustered deployments

Each Node worker maintains its own pug.cache. To keep them in sync without downtime:

• Graceful reload: send a message (e.g., via PM2 pm2 reload or a custom IPC channel) that triggers delete require('pug').cache[key] or require('pug').cache = {} in each worker before it starts accepting new traffic.
• Versioned template filenames: include a content hash or deploy version in the filename (e.g., layout.v12.pug). The new file gets a fresh cache key, so old workers can finish serving the previous version while new workers pick up the updated file.
• Avoid sharing compiled functions via external stores (Redis, Memcached) because serializing a function loses its closure scope and is fragile; prefer the version‑filename approach.

Verification steps

1. Create a minimal Express app with app.enable('view cache') and a Pug view that displays a timestamp.
2. Request the page, note the timestamp, edit the Pug file to change the text, request again – you should see the old timestamp (stale).
3. Add the chokidar watcher shown above, repeat the edit – the second request now shows the updated text.
4. In a cluster (e.g., pm2 start app.js -i 2), hit each worker’s endpoint, edit a template, verify both workers serve stale content until you send a reload signal or restart the workers.

If you are not using Express view cache but calling pug.renderFile directly, replace the app.set step with passing {cache: false} to the render call.