Node.js Reference ยท Module Systems
The require.cache object
How require.cache works in Node.js: one module instance per file, singletons, clearing entries for hot reload, circular requires and what ES modules do instead.
require.cache is the object where CommonJS stores every module it has loaded. Its keys are absolute file names and its values are Module objects holding the exported value, the parent, the children and the load state. The first require() of a file runs it and stores the result; every later require() of the same resolved file returns the stored module.exports without running the file again.
This cache is why a CommonJS module works as a singleton and why editing a file while a program runs changes nothing. Deleting a key makes the next require() load the file afresh, which is the basis of simple hot-reload tools and of test isolation.
// cjs const key = require.resolve('./settings.js'); delete require.cache[key]; const fresh = require('./settings.js');
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
require.cache: { [filename: string]: Module } module.loaded: boolean module.children: Module[] module.parent: Module | null | undefined // deprecated
| Name | Description |
|---|---|
| key | Absolute, resolved file name (use require.resolve() to build it). Built-in modules are not stored here. |
| value | The Module object: exports, id, filename, loaded, children, paths. |
delete require.cache[key] |
Forgets one module. Modules that required it keep their own reference to the old exports. |
Returns: the cache is a plain object, so you read, enumerate and delete it like any other object. Edge cases: assigning your own Module-like value is possible but unsupported, and clearing the cache while a module is still loading leaves a half-built entry behind.
Usage notes
- Singletons for free. Anything exported from a module (a database handle, a configuration object) is shared by every file that requires it, as long as the resolved file name is the same.
- Different paths mean different instances. The same package installed twice under different
node_modulesfolders is loaded twice, and so are two symlinks to one file unless you start Node with--preserve-symlinks. - Circular requires hand out the partially filled
exportsof the module still loading, as the second example shows. Assign toexports.xinstead of replacingmodule.exportsearly, or move the shared code to a third file. - Clearing is shallow. Deleting one key does not delete the entries of the files it required. A true reload needs you to remove each dependent entry, or to restart the process.
- JSON is cached too, so editing a
.jsonfile after the firstrequire()is not visible until the entry is deleted. Read the file withfswhen you need live data. - Do not use it in production code paths. Clearing the cache can leak memory (old modules stay referenced by their importers) and makes behavior hard to predict. It is a tool for tests and development servers.
- ES modules have no such object. Their records live inside the engine, cannot be deleted, and a URL query string such as
import('./x.mjs?v=2')is the usual trick to load a second copy. Each trick leaves the old copy in memory. require.mainis the cache entry of the entry-point file.