Handlebars template cache invalidation strategies in long-running Node.js processes

Direct answer

For production with concurrent renders and direct use of Handlebars.compile, do not delete Handlebars.templates[name] per render. Use a versioned cache key per template version and swap an active pointer only after a successful compile. In a cluster, Handlebars.templates is per-process so invalidation must be coordinated via a shared version signal or process manager.

Confirmed facts

• Handlebars.compile stores compiled templates in Handlebars.templates, a map keyed by name that lives for the process lifetime with no built-in file watching or invalidation.
• Handlebars.templates is per Node.js process. There is no cross-worker propagation.
• Deleting the entry before render forces a re-compile on the next request.

Likely explanation and risks

Deleting Handlebars.templates[name] before each render creates a window where concurrent requests can trigger compile at the same time. If the .hbs file is being overwritten in place, a compile can read a partially written file, causing syntax errors or corrupted output. This risk is higher under load and with non-atomic deployments.

Production-safe steps

1. Generate a version key per file, e.g., templateName + ':' + hashOrMtime. Compute it from the file on a change event or on a periodic check.
2. On change detection, read the file fully, then compile with Handlebars.compile and store under the new version key in Handlebars.templates.
3. Only after successful compile, update an in-process active pointer, e.g., activeVersions[templateName] = newKey, and render using that key.
4. Keep the previous version key live for in-flight renders. Run a periodic sweep to delete version keys not referenced by activeVersions to avoid memory leaks.

Cluster coordination

• Shared store: publish the current version hash via Redis/pubsub. Workers poll or subscribe and reload locally when the hash changes.
• Signal: send SIGHUP to workers to trigger a local reload routine.
• Rolling restart: the most reliable default for production, ensuring all workers start with the same template set.

File-system watchers can trigger the reload, but versioned keys decouple detection from activation and avoid missing or half-compiled templates.

Missing diagnostic detail: Do you overwrite .hbs files in place during deployment or use an atomic symlink swap to a new directory? In-place overwrites increase the partial-write risk and make versioned keys with atomic compile essential; symlink swaps reduce but do not eliminate the need for versioned keys.