Skip to content

Commit

Permalink
doc: improve explanation about built-in modules
Browse files Browse the repository at this point in the history
PR-URL: #52762
Fixes: #52599
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>
  • Loading branch information
joyeecheung authored and targos committed Jun 1, 2024
1 parent c249289 commit 1eb55f3
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 10 deletions.
8 changes: 4 additions & 4 deletions doc/api/esm.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,12 +293,12 @@ mandatory:
| ---------------- | ---------------- |
| `'json'` | [JSON modules][] |

## Builtin modules
## Built-in modules

[Core modules][] provide named exports of their public API. A
[Built-in modules][] provide named exports of their public API. A
default export is also provided which is the value of the CommonJS exports.
The default export can be used for, among other things, modifying the named
exports. Named exports of builtin modules are updated only by calling
exports. Named exports of built-in modules are updated only by calling
[`module.syncBuiltinESMExports()`][].

```js
Expand Down Expand Up @@ -1145,8 +1145,8 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
[6.1.7 Array Index]: https://tc39.es/ecma262/#integer-index
[Addons]: addons.md
[Built-in modules]: modules.md#built-in-modules
[CommonJS]: modules.md
[Core modules]: modules.md#core-modules
[Determining module system]: packages.md#determining-module-system
[Dynamic `import()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import
[ES Module Integration Proposal for WebAssembly]: https://github.com/webassembly/esm-integration
Expand Down
26 changes: 20 additions & 6 deletions doc/api/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -380,7 +380,7 @@ them as different modules and will reload the file multiple times. For example,
`require('./foo')` and `require('./FOO')` return two different objects,
irrespective of whether or not `./foo` and `./FOO` are the same file.

## Core modules
## Built-in modules

<!--type=misc-->

Expand All @@ -396,20 +396,31 @@ changes:
Node.js has several modules compiled into the binary. These modules are
described in greater detail elsewhere in this documentation.

The core modules are defined within the Node.js source and are located in the
The built-in modules are defined within the Node.js source and are located in the
`lib/` folder.

Core modules can be identified using the `node:` prefix, in which case
built-in modules can be identified using the `node:` prefix, in which case
it bypasses the `require` cache. For instance, `require('node:http')` will
always return the built in HTTP module, even if there is `require.cache` entry
by that name.

Some core modules are always preferentially loaded if their identifier is
Some built-in modules are always preferentially loaded if their identifier is
passed to `require()`. For instance, `require('http')` will always
return the built-in HTTP module, even if there is a file by that name. The list
of core modules that can be loaded without using the `node:` prefix is exposed
of built-in modules that can be loaded without using the `node:` prefix is exposed
as [`module.builtinModules`][].

### Built-in modules with mandatory `node:` prefix

When being loaded by `require()`, some built-in modules must be requested with the
`node:` prefix. This requirement exists to prevent newly introduced built-in
modules from having a conflict with user land packages that already have
taken the name. Currently the built-in modules that requires the `node:` prefix are:

* [`node:sea`][]
* [`node:test`][]
* [`node:test/reporters`][]

## Cycles

<!--type=misc-->
Expand Down Expand Up @@ -552,7 +563,7 @@ folders as modules, and work for both `require` and `import`.
<!--type=misc-->

If the module identifier passed to `require()` is not a
[core](#core-modules) module, and does not begin with `'/'`, `'../'`, or
[built-in](#built-in-modules) module, and does not begin with `'/'`, `'../'`, or
`'./'`, then Node.js starts at the directory of the current module, and
adds `/node_modules`, and attempts to load the module from that location.
Node.js will not append `node_modules` to a path already ending in
Expand Down Expand Up @@ -1166,6 +1177,9 @@ This section was moved to
[`module.id`]: #moduleid
[`module` core module]: module.md
[`module` object]: #the-module-object
[`node:sea`]: single-executable-applications.md#single-executable-application-api
[`node:test/reporters`]: test.md#test-reporters
[`node:test`]: test.md
[`package.json`]: packages.md#nodejs-packagejson-field-definitions
[`path.dirname()`]: path.md#pathdirnamepath
[`require.main`]: #requiremain
Expand Down

0 comments on commit 1eb55f3

Please sign in to comment.