diff --git a/doc/api/module.md b/doc/api/module.md index 81e49882def0bf..7ee43f8847f9bf 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -66,6 +66,57 @@ const require = createRequire(import.meta.url); const siblingModule = require('./sibling-module'); ``` +### `module.clearCache(specifier[, options])` + + + +> Stability: 1.1 - Active development + +* `specifier` {string|URL} The module specifier or URL to resolve. The resolved URL/filename + is cleared from the load cache; the specifier (with `parentURL` and `importAttributes`) + is cleared from the resolve cache. +* `options` {Object} + * `mode` {string} Which caches to clear. Supported values are `'all'`, `'commonjs'`, and `'module'`. + **Default:** `'all'`. + * `parentURL` {string|URL} The parent URL used to resolve non-URL specifiers. + For CommonJS, pass `pathToFileURL(__filename)`. For ES modules, pass `import.meta.url`. + * `importAttributes` {Object} Import attributes for ESM resolution. +* Returns: {Object} An object with `{ commonjs: boolean, module: boolean }` indicating whether entries + were removed from each cache. + +Clears the CommonJS `require` cache and/or the ESM module cache for a module. This enables +reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR. +When `mode` is `'all'`, resolution failures for one module system do not throw; check the +returned flags to see what was cleared. +This also clears resolution cache entries for that specifier. Clearing a module does not clear +cached entries for its dependencies, and other specifiers that resolve to the same target may +remain. +When a `file:` URL is resolved, cached module jobs for the same file path are cleared even if +they differ by search or hash. + +```mjs +import { clearCache } from 'node:module'; + +const url = new URL('./mod.mjs', import.meta.url); +await import(url.href); + +clearCache(url); +await import(url.href); // re-executes the module +``` + +```cjs +const { clearCache } = require('node:module'); +const path = require('node:path'); + +const file = path.join(__dirname, 'mod.js'); +require(file); + +clearCache(file); +require(file); // re-executes the module +``` + ### `module.findPackageJSON(specifier[, base])`