Skip to content

Commit 0f08a8e

Browse files
BridgeARBethGriggs
authored andcommitted
doc: add information about modules cache behavior
This publicly documents that adding native module names will resolve the added entry instead of the native module. It also updates the description why extensions are deprecated. PR-URL: #26971 Refs: #25362 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Signed-off-by: Beth Griggs <Bethany.Griggs@uk.ibm.com>
1 parent b88871e commit 0f08a8e

File tree

1 file changed

+25
-31
lines changed

1 file changed

+25
-31
lines changed

doc/api/modules.md

+25-31
Original file line numberDiff line numberDiff line change
@@ -196,28 +196,26 @@ NODE_MODULES_PATHS(START)
196196

197197
<!--type=misc-->
198198

199-
Modules are cached after the first time they are loaded. This means
200-
(among other things) that every call to `require('foo')` will get
201-
exactly the same object returned, if it would resolve to the same file.
199+
Modules are cached after the first time they are loaded. This means (among other
200+
things) that every call to `require('foo')` will get exactly the same object
201+
returned, if it would resolve to the same file.
202202

203-
Provided `require.cache` is not modified, multiple calls to
204-
`require('foo')` will not cause the module code to be executed multiple times.
205-
This is an important feature. With it, "partially done" objects can be returned,
206-
thus allowing transitive dependencies to be loaded even when they would cause
207-
cycles.
203+
Provided `require.cache` is not modified, multiple calls to `require('foo')`
204+
will not cause the module code to be executed multiple times. This is an
205+
important feature. With it, "partially done" objects can be returned, thus
206+
allowing transitive dependencies to be loaded even when they would cause cycles.
208207

209-
To have a module execute code multiple times, export a function, and call
210-
that function.
208+
To have a module execute code multiple times, export a function, and call that
209+
function.
211210

212211
### Module Caching Caveats
213212

214213
<!--type=misc-->
215214

216-
Modules are cached based on their resolved filename. Since modules may
217-
resolve to a different filename based on the location of the calling
218-
module (loading from `node_modules` folders), it is not a *guarantee*
219-
that `require('foo')` will always return the exact same object, if it
220-
would resolve to different files.
215+
Modules are cached based on their resolved filename. Since modules may resolve
216+
to a different filename based on the location of the calling module (loading
217+
from `node_modules` folders), it is not a *guarantee* that `require('foo')` will
218+
always return the exact same object, if it would resolve to different files.
221219

222220
Additionally, on case-insensitive file systems or operating systems, different
223221
resolved filenames can point to the same file, but the cache will still treat
@@ -412,7 +410,7 @@ are not found elsewhere.
412410
On Windows, `NODE_PATH` is delimited by semicolons (`;`) instead of colons.
413411

414412
`NODE_PATH` was originally created to support loading modules from
415-
varying paths before the current [module resolution][] algorithm was frozen.
413+
varying paths before the current [module resolution][] algorithm was defined.
416414

417415
`NODE_PATH` is still supported, but is less necessary now that the Node.js
418416
ecosystem has settled on a convention for locating dependent modules.
@@ -585,6 +583,11 @@ value from this object, the next `require` will reload the module. Note that
585583
this does not apply to [native addons][], for which reloading will result in an
586584
error.
587585

586+
Adding or replacing entries is also possible. This cache is checked before
587+
native modules and if a name matching a native module is added to the cache,
588+
no require call is
589+
going to receive the native module anymore. Use with care!
590+
588591
#### require.extensions
589592
<!-- YAML
590593
added: v0.3.0
@@ -603,22 +606,13 @@ Process files with the extension `.sjs` as `.js`:
603606
require.extensions['.sjs'] = require.extensions['.js'];
604607
```
605608

606-
**Deprecated.** In the past, this list has been used to load
607-
non-JavaScript modules into Node.js by compiling them on-demand.
608-
However, in practice, there are much better ways to do this, such as
609-
loading modules via some other Node.js program, or compiling them to
610-
JavaScript ahead of time.
611-
612-
Since the module system is locked, this feature will probably never go
613-
away. However, it may have subtle bugs and complexities that are best
614-
left untouched.
615-
616-
Note that the number of file system operations that the module system
617-
has to perform in order to resolve a `require(...)` statement to a
618-
filename scales linearly with the number of registered extensions.
609+
**Deprecated.** In the past, this list has been used to load non-JavaScript
610+
modules into Node.js by compiling them on-demand. However, in practice, there
611+
are much better ways to do this, such as loading modules via some other Node.js
612+
program, or compiling them to JavaScript ahead of time.
619613

620-
In other words, adding extensions slows down the module loader and
621-
should be discouraged.
614+
Avoid using `require.extensions`. Use could cause subtle bugs and resolving the
615+
extensions gets slower with each registered extension.
622616

623617
#### require.main
624618
<!-- YAML

0 commit comments

Comments
 (0)