module: add clearCache for CJS and ESM

[anonrig]

Introduce Module.clearCache() to invalidate CommonJS and ESM module caches with optional resolution context, enabling HMR-like reloads. Document the API and add tests/fixtures to cover cache invalidation behavior.

[nodejs-github-bot]

Review requested:

• @nodejs/loaders

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @anonrig.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[mcollina]

I’m relatively +1 on having this in Node.js, but I recall having a a lot of discussions about this @GeoffreyBooth and @nodejs/loaders teams about this, and it would massively break the spec, expectations, and invariants regarding ESM.

(Note, this is what people have been asking us to add for a long time).

My personal objection to this API is that it would inadvertently leak memory at every turn, so while this sounds good in theory, in practice it would significantly backfire in long-running scenarios. An option could be to expose it only behind a flag, putting the user in charge of choosing this behavior.

Every single scenario where I saw HMR in Node.js ends up in memory leaks. This is the reason why I had so much interest and hopes for ShadowRealm.

[benjamingr]

I am still +1 on the feature from a user usability point of view. Code lgtm.

[benjamingr]

Every single scenario where I saw HMR in Node.js ends up in memory leaks. This is the reason why I had so much interest and hopes for ShadowRealm.

We're giving users a tool, it may be seen as a footgun by some but hopefully libraries that use the API correctly and warn users about incorrect usage emerge.

[anonrig]

@mcollina Thanks for the feedback. I agree the ESM semantics concerns are real. This API doesn’t change the core ESM invariants (single instance per URL); it only removes Node's internal cache entries to allow explicit reloads in opt‑in workflows. Even with that, existing references (namespaces, listeners, closures) can keep old graphs alive, so this is still potentially leaky unless the app does explicit disposal. I’ll make sure the docs call out the risks and the fact that this only clears Node’s internal caches, and I’d like loader team input on the final shape of the API.

This commit should address some of your concerns. b3bd79a

I am still +1 on the feature from a user usability point of view. Code lgtm.

Thanks for the review @benjamingr. Would you mind re-reviewing again so I can trigger CI?

[Nsttt]

Thanks a lot for this ❤️

[Jamesernator]

Rather than violating ESM invariants, can't node just provide a function that imports a url?

i.e. While the given example of:

const url = new URL('./mod.mjs', import.meta.url);
await import(url.href);

clearCache(url);
await import(url.href); // re-executes the module

is indeed not spec compliant, it's perfectly legal to have something like:

import { clearCache, importModule } from "node:module";

await importModule(someUrl);
clearCache();
await importModule(someUrl); // reexecute

[codecov]

Codecov Report

❌ Patch coverage is 93.40659% with 36 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.66%. Comparing base (2e1265a) to head (0b472a6).
⚠️ Report is 32 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/modules/clear.js	91.38%	31 Missing ⚠️
lib/internal/modules/esm/module_map.js	91.17%	3 Missing ⚠️
src/node_modules.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61767      +/-   ##
==========================================
- Coverage   89.72%   89.66%   -0.06%     
==========================================
  Files         676      677       +1     
  Lines      206065   206856     +791     
  Branches    39508    39619     +111     
==========================================
+ Hits       184897   185484     +587     
- Misses      13315    13502     +187     
- Partials     7853     7870      +17     

Files with missing lines	Coverage Δ
lib/internal/modules/cjs/loader.js	98.16% <100.00%> (-0.20%)	⬇️
lib/internal/modules/esm/loader.js	98.79% <100.00%> (+0.03%)	⬆️
lib/internal/modules/esm/translators.js	97.86% <100.00%> (+0.21%)	⬆️
lib/internal/modules/package_json_reader.js	99.74% <100.00%> (+0.29%)	⬆️
lib/module.js	100.00% <100.00%> (ø)
src/node_modules.h	100.00% <ø> (ø)
src/node_modules.cc	80.55% <87.50%> (+0.74%)	⬆️
lib/internal/modules/esm/module_map.js	98.18% <91.17%> (-0.30%)	⬇️
lib/internal/modules/clear.js	91.38% <91.38%> (ø)

... and 49 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[joyeecheung]

While I am +1 to the idea in general, I am afraid the current API may bring more problem than it solves...see the comments.

(Granted it isn't really a problem unique to this specific design, I think the issue is more that this is not a very well solved problem so far, I don't really know what it should look like, though I think I might be able to point out what it should not look like to avoid adding/re-introducing leaks/use-after-frees that user land workarounds can already manage)

[ScriptedAlchemy]

I was the one requesting this while sitting next to yagiz today.
Some context:

We take advantage of Module Federation which allows us to distribute code at runtime. However, when parts of the distributed system are updated, it gets stuck in module cache.

I've had some workarounds, like attempting to purge require cache - however when it comes to esm, it's a difficult problem. Since we do this distribution primarily in production, and there can be thousands of updates a day, I block esm from being supported because it'll leak memory - which was fine for several years but becoming more problematic in modern tooling.

On lambda we cannot just exit a process and bring a new one up without triggering a empty deploy, which has generally been a perf hit to cold start a new lambda vs try and "reset" the module cache for primitive hot reload.

Now, I know this might be controversial, or not recommended - but the reality is that many large companies use federation, most fortune 50 companies use it heavily. All of them are relying on userland cobbling I've created. If there is a solution, it would be greatly appreciated by all of my users.

I believe this would also be very useful in general for tooling like rspack etc where we have universal dev serves.

If invalidation of specific modules causes complexity, I'd be more than happy with a nuclear option like resetModuleCache() which just clears everything entirely. Would be a little slower, but nothing is slower than killing a process and bringing up a new one.

"Soft Restart" node without killing it.
Yes, I'm aware of various footguns like globals, prototype pollution etc.
These so far have been easy to mitigate and none of the user base has reported any major issues around it, whereas my cobbled together solution poses a much bigger issue vs footguns.

Don't have much opinion on spec compliance etc, can go through NAPI as well if that would avoid any spec concerns or pushback.

[jsumners-nr]

Chiming in to say that re-loading a module is very helpful in tests. We can do this with the fabulous CJS paradigm, but ESM does not have a viable equivalent and it should.

[joyeecheung]

I think there are still quite a few places that need updates/tests - I tried my best to find them, but there are some dusty corners in the module loader that I have never poked at, you might want to take a heap snapshot or write more tests with v8.queryObject() to verify:

• What happens when a closure in a module errors (or more specifically when the error stack is prepared by poking at various caches) after the cache of the original module is cleared? Especially if it has source maps and --enable-source-maps is on?
• This is tricky, but cjsModule[parent] and cjsModule[kLastModuleParent] could need an update too if you yank the parents out of the cache. Otherwise the parent can get leaked.
• When dynamic import(cjs) happens, there can be a point where the CJS module cache entry for the requested module and its dependencies are synchronously populated for export detection, but they will only be compiled and evaluated in the next microtask queue checkpoint, yet here import() itself can already return since it's async, and some code elsewhere could clear the cache before another checkpoint (likely an await) actually spins the evaluation - in the evaluation callback of cjs facades, it will then try to look up the caches again, and see a mismatch between "module whose exports are detected" v.s. "module that's actually being compiled and evaluated" - races of this kind has been a source of subtle bugs, we sort of made most of them go away by making resolution and loading entirely synchronous, but the cache clearing can expose new internal details that add another bug surface that's worth checking.
• The cjsCache in the esm translators (there's a TODO about using WeakMap instead, maybe that works?)
• The wasm facade module has a custom import.meta initializer that contains a closure (implemented in createDynamicModule), which in turn has references crossing the wasm boundary, not sure if that can create another source of leaks.

[anonrig]

I think I addressed all of your concerns @joyeecheung. Let me know if I missed anything!

[GeoffreyBooth]

I’m relatively +1 on having this in Node.js, but I recall having a a lot of discussions about this @GeoffreyBooth and @nodejs/loaders teams about this, and it would massively break the spec, expectations, and invariants regarding ESM.

Just pinging @guybedford to speak on the spec concerns. I think we should wait for him or someone similarly knowledgeable about the spec to comment before landing.

In general I'm +1 on the feature, assuming it can be safely implemented. My (dim) recollection was that the last time we considered it, it was impossible to modify an ES module after it had been loaded into V8. Has that changed in recent years? How do you handle cases like import { foo } from './bar.js' where bar.js gets reloaded and no longer has a foo export, and the importing code calls foo()? That was part of the complexity, that ESM has this linking stage and so presumably replaced modules need to have the same shapes/exports or else the linking gets invalidated.

[joyeecheung]

I think one way to test this more robustly (i.e. V8 can actually garbage collect it) might be something like this:

// Flags: --expose-internals
const { internalBinding } = require('internal/test/binding');
const { ModuleWrap } = internalBinding('module_wrap');
const { queryObjects } require('node:v8');  // Let's run the test in CJS to reduce the noise from queryObject
let app, rev = 0;
const reload = async () => {
  const prev = rev ? `./app.mjs?hmr=${rev}` : null;
  if (prev) {
    module.clearCache(prev, {
      parentURL: import.meta.url,
      resolver: "import",
      caches: "all",
    });
  }
  app = await import(`./app.mjs?hmr=${++rev}`);
};

(async() {
  await reload();  // first load
  await reload();  // second
  const result = queryObjects(ModuleWrap, { format: 'summary' });
  // Validate that result no longer includes module with a wrap whose .url includes `app.mjs?hmr=0`
})();

(Or use checkIfCollectableByCounting with ModuleWrap)

[anonrig]

@joyeecheung Pushed a new test according to your recommendations.

[anonrig]

@joyeecheung @mcollina would you mind re-reviewing?

[mcollina]

lgtm

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71505/

[anonrig]

@guybedford @joyeecheung @GeoffreyBooth I'd like to land this on Monday, but I want to make sure we are all aligned with this change. Would you mind reviewing or leave a comment about your thoughts? Just don't forget that this is an "active development" API which we can iterate over time.

[thescientist13]

Just wanted to chime in that since going full ESM a few years ago, this has been one of the biggest things I've been missing over CJS, for live reloading NodeJS code for local development based workflows (been using Worker Threads as a fallback).

Very much looking forward to this one! 💚

[GeoffreyBooth]

@guybedford @joyeecheung @GeoffreyBooth I'd like to land this on Monday, but I want to make sure we are all aligned with this change. Would you mind reviewing or leave a comment about your thoughts? Just don't forget that this is an "active development" API which we can iterate over time.

I defer to @joyeecheung on the technical review and to @guybedford on the spec compliance, so if both of them approve then it seems good to me!

One thing I'm wondering about is what about people using this in production. It's obviously designed only for development, but nothing stops someone from using this API anywhere, or for dependencies calling it; is that a concern? Could it be a security concern if a malicious dependency calls this in production? I assume not since what this does is basically already possible in CommonJS, but it might be something worth addressing if only in a comment.

[joyeecheung]

It's obviously designed only for development, but nothing stops someone from using this API anywhere, or for dependencies calling it; is that a concern? Could it be a security concern if a malicious dependency calls this in production?

I think according to the threat model this can't be a security concern for Node.js per-se - Node.js trusts all code it's given. Although if the user framework has additional security guarantees they'll need to be responsible in making sure the API is used correctly.

Although considering this is a pretty early design and we don't know for sure yet if this is good enough for HMR solution in the wild, it may be a good idea to emit an experimental warning for now and wait for some feedback from HMR solutions actually integrating it with current release to validate the API is not flawed, before removing that warning. Otherwise there's a risk that if this does not work correctly for some packages and requires breaking changes to fix, it can get rather complicated to break if other popular packages start to rely on the design as-is.

[laverdet]

One thing I'm wondering about is what about people using this in production. It's obviously designed only for development, but nothing stops someone from using this API anywhere, or for dependencies calling it; is that a concern?

Yeah the production use-cases here are really iffy to me. It seems like people want to use this to work around Lambda cold starts which seems bonkers and there are a million other correct ways to solve that problem.

Unit tests should be using vm.

For hot reloading you need a more complete solution. Though this PR would fix the memory leak issue.

I'm not sure if the concerns raised in #50618 are still relevant but I received some pushback on the specification violations in 2023.

[jsumners-nr]

Unit tests should be using vm.

I am unfamiliar. Can you elaborate?

[simlu]

Unit tests should be using vm.

I am unfamiliar. Can you elaborate?

Not sure about vm, I remember not being able to get it to work for our use case. But this is what we've been using for hot reloading (with memory leak):
https://github.com/blackflux/lambda-tdd/blob/master/package.json#L11
https://github.com/blackflux/lambda-tdd/blob/master/test/reg.js
https://github.com/blackflux/lambda-tdd/blob/master/test/hot.js

Don't get me wrong. I would have loved this pr many years ago but the pushback has always been that this was already possible in userland and not needed. So I'm curious what use cases this pr solves that can't already be done through something discussed here: #49442

Or is this pr just to make those uses cases easier to implement?

[Nsttt]

Or is this pr just to make those uses cases easier to implement?

From my side, on Module Federation setups its fairly relevant, regardless the environment.

In Module Federation systems, remotes and manifests can change frequently while the same Node process stays warm.
That means we need a reliable way to invalidate old modules and load new ones without killing the process every time.

The userland options we have today (require.cache deletion, cache-busting import URLs, custom loader tricks like #49442) can help, but they don’t fully reset the combined CJS + ESM cache behavior inside Node. In practice we still hit stale module graphs, duplicate shared/singleton state, and memory growth over time, especially on complex setups such as Bytedance's.

That maps directly to what we do in Zephyr as well, where thanks to our system we can take advantage of controlling the serving end, and being able to enable HMR programatically on any URL that we control.

Imagine a URL such as dashboard.my.app conformed of multiple, independent Apps (and URLs), where you can turn on HMR on the given deployment target, and granularly update specific federated parts (a button, a form, a library, etc...) where you need it without having to reload or care about scalability due to memory issues.

[laverdet]

I am unfamiliar. Can you elaborate?

vm has been a core nodejs module for like 15 years. This would be a concern of your unit test framework. Not the end user building unit tests.

---

In practice we still hit stale module graphs

Stale module graphs seem like a huge concern. Even with this PR existing references to module namespaces cannot be invalidated. In these kinds of deployments are you just doing await import all over the place?

[Nsttt]

Stale module graphs seem like a huge concern. Even with this PR existing references to module namespaces cannot be invalidated. In these kinds of deployments are you just doing await import all over the place?

Nah, in Module Federation setups we're not scattering await import() through app code.

We keep dynamic loading at the federation boundary via loadRemote, and for updates we do
controlled remote cutovers with registerRemotes(..., { force: true }), which
clears old runtime cache paths for future resolutions.

Live namespace/object references can’t be revoked once handed out. So we treat updates as cutovers: new requests go to the new graph, in-flight work drains, then old graph cleanup/dispose runs.

Sorry if its a bit off-topic 😄

[jsumners-nr]

I am unfamiliar. Can you elaborate?

vm has been a core nodejs module for like 15 years. This would be a concern of your unit test framework. Not the end user building unit tests.

I know what the vm module is. I am unclear how "unit tests should be using vm" solves what this PR is meant to accomplish.

[laverdet]

I am unclear how "unit tests should be using vm" solves what this PR is meant to accomplish.

A unit test environment should be using ephemeral realms. Otherwise shared global state would cause tests to interfere with each other. Module graphs created via vm are handled by the user, so the leak issue is not a concern. My opinion is that any unit test framework which reaches for this API is doing it wrong.

Nah, in Module Federation setups we're not scattering await import() through app code.

I see. It's not the deployment model I would choose in an ideal world but I can see how a team would end up here.

---

I think the stakeholders need to make a call on whether or not encouraging the specification violation is important. HostLoadImportedModule is crystal clear that non-throw results should be idempotent. If it's important to adhere to the spec (perhaps v8 does enforce this later, I don't imagine they would though) then you would want tombstones.

This is super bike sheddy but I want to point out that the term cache here raises an eyebrow. A cache is something used primarily for performance. The module map structure enforces correctness, therefore it is a store, map, or something else. Whatever nodejs calls it internally, it may be good to give it a second thought for a public API. In #50618 I called the function releaseLoadedModule. The term cache here echoes back to require.cache which was also not correctly named. d8 (v8) calls it module_map: https://github.com/v8/v8/blob/76f8c9ec45f2a3b64e23ada07a6e7b19ca252fa1/src/d8/d8.cc#L775

Arguably hot reloaders are a significant enough departure from a classic module graph that they should be implemented directly via vm. In this world the only thing in the primary nodejs realm would be the hot reloading framework. Then the framework could do whatever it wanted with the module graph that it manages on its own. nodejs/loaders#26 and nodejs/loaders#116 would make those solutions more palatable.