Why Node.js Hot Module Reload Can Leak Memory—and How to Avoid It

When Node.js first emerged around 2015, developers were eager for hot‑update techniques that let business logic change without restarting the server, offering zero‑downtime and millisecond‑level updates.

Hot‑Update Principle

Understanding Node.js's module system is essential. When a parent module A requires a child module B, Node checks the cache ( require.cache) and, if absent, compiles B, adds it to the cache, and records the relationship in the parent’s children array.

To avoid memory leaks during hot‑updates, the references from the parent to the child must be fully removed.

Problem 1: Memory Leak

Using the decache package, a test repeatedly clears and re‑requires ./update_mod.js, which creates a large array to expose leaks. Memory usage quickly grows, and heap snapshots reveal that the parent module’s children array accumulates duplicate entries of the hot‑updated module, causing the leak.

'use strict';
const cleanCache = require('decache');
let mod = require('./update_mod.js');
mod();
mod();
setInterval(() => {
  cleanCache('./update_mod.js');
  mod = require('./update_mod.js');
  mod();
}, 100);

The decache implementation only clears require.cache, leaving the children references intact, which explains the persistent leak.

Problem 2: Resource Leak

Even when clear-module removes cache entries, resources such as timers created inside the hot‑updated module remain alive. A simple module that starts a setInterval continues to run after the module is cleared, demonstrating a resource leak.

'use strict';
const start = new Date().toLocaleString();
setInterval(() => console.log(start), 1000);

Problem 3: ESM Compatibility

Both decache and clear-module rely on CommonJS. Native ESModules (ESM) are handled by the V8 engine, and current hot‑update tools cannot unload ESM modules. Experimental ESM hooks exist in Node.js but are still unstable.

Problem 4: Version Chaos

Hot‑updating can leave multiple versions of a module in memory because the parent’s children array may still reference older instances. This leads to confusing bugs and hidden memory consumption.

Suitable Scenarios for Hot‑Update

In development environments, minor memory or resource leaks may be acceptable for faster iteration. In production, hot‑updates are only safe for tightly‑coupled modules without side‑effects such as open sockets or timers.

Overall, hot‑module replacement is a double‑edged sword: it can boost developer productivity but also introduces subtle memory, resource, and versioning issues that require deep understanding of Node.js’s module internals.