diff --git a/doc/api/cli.md b/doc/api/cli.md
index b5346f949d14fa..f590ebd0c89deb 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -28,8 +28,8 @@ absolute path, it's resolved as a relative path from the current working
directory. That path is then resolved by [CommonJS][] module loader. If no
corresponding file is found, an error is thrown.
-If a file is found, its path will be passed to the [ECMAScript module loader][]
-under any of the following conditions:
+If a file is found, its path will be passed to the
+[ES module loader][Modules loaders] under any of the following conditions:
* The program was started with a command-line flag that forces the entry
point to be loaded with ECMAScript module loader.
@@ -43,9 +43,9 @@ Otherwise, the file is loaded using the CommonJS module loader. See
### ECMAScript modules loader entry point caveat
-When loading [ECMAScript module loader][] loads the program entry point, the `node`
-command will only accept as input only files with `.js`, `.mjs`, or `.cjs`
-extensions; and with `.wasm` extensions when
+When loading, the [ES module loader][Modules loaders] loads the program
+entry point, the `node` command will accept as input only files with `.js`,
+`.mjs`, or `.cjs` extensions; and with `.wasm` extensions when
[`--experimental-wasm-modules`][] is enabled.
## Options
@@ -550,7 +550,11 @@ changes:
`--experimental-loader`.
-->
-Specify the `module` of a custom experimental [ECMAScript module loader][].
+> This flag is discouraged and may be removed in a future version of Node.js.
+> Please use
+> [`--import` with `register()`][module customization hooks: enabling] instead.
+
+Specify the `module` containing exported [module customization hooks][].
`module` may be any string accepted as an [`import` specifier][].
### `--experimental-network-imports`
@@ -2644,9 +2648,10 @@ done
[CommonJS module]: modules.md
[CustomEvent Web API]: https://dom.spec.whatwg.org/#customevent
[ECMAScript module]: esm.md#modules-ecmascript-modules
-[ECMAScript module loader]: esm.md#loaders
[Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
[File System Permissions]: permissions.md#file-system-permissions
+[Module customization hooks]: module.md#customization-hooks
+[Module customization hooks: enabling]: module.md#enabling
[Modules loaders]: packages.md#modules-loaders
[Node.js issue tracker]: https://github.com/nodejs/node/issues
[OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html
diff --git a/doc/api/esm.md b/doc/api/esm.md
index d56a184a74bcbf..b3df8fa80fb7bb 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -1070,7 +1070,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
[`process.dlopen`]: process.md#processdlopenmodule-filename-flags
[cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer/tree/1.2.2
[commonjs-extension-resolution-loader]: https://github.com/nodejs/loaders-test/tree/main/commonjs-extension-resolution-loader
-[custom https loader]: module.md#https-loader
+[custom https loader]: module.md#import-from-https
[import.meta.resolve]: #importmetaresolvespecifier
[percent-encoded]: url.md#percent-encoding-in-urls
[special scheme]: https://url.spec.whatwg.org/#special-scheme
diff --git a/doc/api/module.md b/doc/api/module.md
index 7e41cc30827918..6e4b3429595863 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -102,114 +102,7 @@ added: REPLACEME
* Returns: {any} returns whatever was returned by the `initialize` hook.
Register a module that exports [hooks][] that customize Node.js module
-resolution and loading behavior.
-
-```mjs
-import { register } from 'node:module';
-
-register('http-to-https', import.meta.url);
-
-// Because this is a dynamic `import()`, the `http-to-https` hooks will run
-// before importing `./my-app.mjs`.
-await import('./my-app.mjs');
-```
-
-In the example above, we are registering the `http-to-https` loader,
-but it will only be available for subsequently imported modules—in
-this case, `my-app.mjs`. If the `await import('./my-app.mjs')` had
-instead been a static `import './my-app.mjs'`, _the app would already
-have been loaded_ before the `http-to-https` hooks were
-registered. This is part of the design of ES modules, where static
-imports are evaluated from the leaves of the tree first back to the
-trunk. There can be static imports _within_ `my-app.mjs`, which
-will not be evaluated until `my-app.mjs` is when it's dynamically
-imported.
-
-The `--experimental-loader` flag of the CLI can be used together
-with the `register` function; the hooks registered with the
-function will follow the same evaluation chain of hooks registered
-within the CLI:
-
-```console
-node \
- --experimental-loader unpkg \
- --experimental-loader http-to-https \
- --experimental-loader cache-buster \
- entrypoint.mjs
-```
-
-```mjs
-// entrypoint.mjs
-import { URL } from 'node:url';
-import { register } from 'node:module';
-
-const loaderURL = new URL('./my-programmatically-loader.mjs', import.meta.url);
-
-register(loaderURL);
-await import('./my-app.mjs');
-```
-
-The `my-programmatic-loader.mjs` can leverage `unpkg`,
-`http-to-https`, and `cache-buster` loaders.
-
-It's also possible to use `register` more than once:
-
-```mjs
-// entrypoint.mjs
-import { URL } from 'node:url';
-import { register } from 'node:module';
-
-register(new URL('./first-loader.mjs', import.meta.url));
-register('./second-loader.mjs', import.meta.url);
-await import('./my-app.mjs');
-```
-
-Both loaders (`first-loader.mjs` and `second-loader.mjs`) can use
-all the resources provided by the loaders registered in the CLI. But
-remember that they will only be available in the next imported
-module (`my-app.mjs`). The evaluation order of the hooks when
-importing `my-app.mjs` and consecutive modules in the example above
-will be:
-
-```console
-resolve: second-loader.mjs
-resolve: first-loader.mjs
-resolve: cache-buster
-resolve: http-to-https
-resolve: unpkg
-load: second-loader.mjs
-load: first-loader.mjs
-load: cache-buster
-load: http-to-https
-load: unpkg
-globalPreload: second-loader.mjs
-globalPreload: first-loader.mjs
-globalPreload: cache-buster
-globalPreload: http-to-https
-globalPreload: unpkg
-```
-
-This function can also be used to pass data to the loader's [`initialize`][]
-hook; the data passed to the hook may include transferrable objects like ports.
-
-```mjs
-import { register } from 'node:module';
-import { MessageChannel } from 'node:worker_threads';
-
-// This example showcases how a message channel can be used to
-// communicate to the loader, by sending `port2` to the loader.
-const { port1, port2 } = new MessageChannel();
-
-port1.on('message', (msg) => {
- console.log(msg);
-});
-
-register('./my-programmatic-loader.mjs', {
- parentURL: import.meta.url,
- data: { number: 1, port: port2 },
- transferList: [port2],
-});
-```
+resolution and loading behavior. See [Customization hooks][].
### `module.syncBuiltinESMExports()`
@@ -250,6 +143,8 @@ import('node:fs').then((esmFS) => {
});
```
+
+
## Customization Hooks
-> Stability: 1 - Experimental
-
-> This API is currently being redesigned and will still change.
+> Stability: 1.1 - Active development
-To customize the default module resolution, loader hooks can optionally be
-provided via a `--experimental-loader ./loader-name.mjs` argument to Node.js.
+
+
+### Enabling
+
+Module resolution and loading can be customized by registering a file which
+exports a set of hooks. This can be done using the [`register`][] method
+from `node:module`, which you can run before your application code by
+using the `--import` flag:
+
+```bash
+node --import ./register-hooks.js ./my-app.js
+```
+
+```mjs
+// register-hooks.js
+import { register } from 'node:module';
+
+register('./hooks.mjs', import.meta.url);
+```
+
+```cjs
+// register-hooks.js
+const { register } = require('node:module');
+const { pathToFileURL } = require('node:url');
+
+register('./hooks.mjs', pathToFileURL(__filename));
+```
+
+The file passed to `--import` can also be an export from a dependency:
+
+```bash
+node --import some-package/register ./my-app.js
+```
+
+Where `some-package` has an [`"exports"`][] field defining the `/register`
+export to map to a file that calls `register()`, like the following `register-hooks.js`
+example.
+
+Using `--import` ensures that the hooks are registered before any application
+files are imported, including the entry point of the application. Alternatively,
+`register` can be called from the entry point, but dynamic `import()` must be
+used for any code that should be run after the hooks are registered:
+
+```mjs
+import { register } from 'node:module';
+
+register('http-to-https', import.meta.url);
+
+// Because this is a dynamic `import()`, the `http-to-https` hooks will run
+// to handle `./my-app.js` and any other files it imports or requires.
+await import('./my-app.js');
+```
+
+```cjs
+const { register } = require('node:module');
+const { pathToFileURL } = require('node:url');
+
+register('http-to-https', pathToFileURL(__filename));
+
+// Because this is a dynamic `import()`, the `http-to-https` hooks will run
+// to handle `./my-app.js` and any other files it imports or requires.
+import('./my-app.js');
+```
+
+In this example, we are registering the `http-to-https` hooks, but they will
+only be available for subsequently imported modules—in this case, `my-app.js`
+and anything it references via `import` (and optionally `require`). If the
+`import('./my-app.js')` had instead been a static `import './my-app.js'`, the
+app would have _already_ been loaded **before** the `http-to-https` hooks were
+registered. This due to the ES modules specification, where static imports are
+evaluated from the leaves of the tree first, then back to the trunk. There can
+be static imports _within_ `my-app.js`, which will not be evaluated until
+`my-app.js` is dynamically imported.
-When hooks are used they apply to each subsequent loader, the entry point, and
-all `import` calls. They won't apply to `require` calls; those still follow
-[CommonJS][] rules.
+`my-app.js` can also be CommonJS. Customization hooks will run for any
+modules that it references via `import` (and optionally `require`).
-Loaders follow the pattern of `--require`:
+Finally, if all you want to do is register hooks before your app runs and you
+don't want to create a separate file for that purpose, you can pass a `data:`
+URL to `--import`:
```bash
-node \
- --experimental-loader unpkg \
- --experimental-loader http-to-https \
- --experimental-loader cache-buster
+node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("http-to-https", pathToFileURL("./"));' ./my-app.js
```
-These are called in the following sequence: `cache-buster` calls
-`http-to-https` which calls `unpkg`.
+### Chaining
+
+It's possible to call `register` more than once:
+
+```mjs
+// entrypoint.mjs
+import { register } from 'node:module';
+
+register('./first.mjs', import.meta.url);
+register('./second.mjs', import.meta.url);
+await import('./my-app.mjs');
+```
+
+```cjs
+// entrypoint.cjs
+const { register } = require('node:module');
+const { pathToFileURL } = require('node:url');
+
+const parentURL = pathToFileURL(__filename);
+register('./first.mjs', parentURL);
+register('./second.mjs', parentURL);
+import('./my-app.mjs');
+```
+
+In this example, the registered hooks will form chains. If both `first.mjs` and
+`second.mjs` define a `resolve` hook, both will be called, in the order they
+were registered. The same applies to all the other hooks.
+
+The registered hooks also affect `register` itself. In this example,
+`second.mjs` will be resolved and loaded per the hooks registered by
+`first.mjs`. This allows for things like writing hooks in non-JavaScript
+languages, so long as an earlier registered loader is one that transpiles into
+JavaScript.
+
+The `register` method cannot be called from within the module that defines the
+hooks.
+
+### Communication with module customization hooks
+
+Module customization hooks run on a dedicated thread, separate from the main
+thread that runs application code. This means mutating global variables won't
+affect the other thread(s), and message channels must be used to communicate
+between the threads.
+
+The `register` method can be used to pass data to an [`initialize`][] hook. The
+data passed to the hook may include transferrable objects like ports.
+
+```mjs
+import { register } from 'node:module';
+import { MessageChannel } from 'node:worker_threads';
+
+// This example demonstrates how a message channel can be used to
+// communicate with the hooks, by sending `port2` to the hooks.
+const { port1, port2 } = new MessageChannel();
+
+port1.on('message', (msg) => {
+ console.log(msg);
+});
+
+register('./my-hooks.mjs', {
+ parentURL: import.meta.url,
+ data: { number: 1, port: port2 },
+ transferList: [port2],
+});
+```
+
+```cjs
+const { register } = require('node:module');
+const { pathToFileURL } = require('node:url');
+const { MessageChannel } = require('node:worker_threads');
+
+// This example showcases how a message channel can be used to
+// communicate with the hooks, by sending `port2` to the hooks.
+const { port1, port2 } = new MessageChannel();
+
+port1.on('message', (msg) => {
+ console.log(msg);
+});
+
+register('./my-hooks.mjs', {
+ parentURL: pathToFileURL(__filename),
+ data: { number: 1, port: port2 },
+ transferList: [port2],
+});
+```
### Hooks
+The [`register`][] method can be used to register a module that exports a set of
+hooks. The hooks are functions that are called by Node.js to customize the
+module resolution and loading process. The exported functions must have specific
+names and signatures, and they must be exported as named exports.
+
+```mjs
+export async function initialize({ number, port }) {
+ // Receive data from `register`, return data to `register`.
+}
+
+export async function resolve(specifier, context, nextResolve) {
+ // Take an `import` or `require` specifier and resolve it to a URL.
+}
+
+export async function load(url, context, nextLoad) {
+ // Take a resolved URL and return the source code to be evaluated.
+}
+```
+
Hooks are part of a chain, even if that chain consists of only one custom
(user-provided) hook and the default hook, which is always present. Hook
functions nest: each one must always return a plain object, and chaining happens
-as a result of each function calling `next()`, which is a reference
-to the subsequent loader's hook.
+as a result of each function calling `next()`, which is a reference to
+the subsequent loader's hook.
-A hook that returns a value lacking a required property triggers an exception.
-A hook that returns without calling `next()` _and_ without returning
+A hook that returns a value lacking a required property triggers an exception. A
+hook that returns without calling `next()` _and_ without returning
`shortCircuit: true` also triggers an exception. These errors are to help
-prevent unintentional breaks in the chain.
+prevent unintentional breaks in the chain. Return `shortCircuit: true` from a
+hook to signal that the chain is intentionally ending at your hook.
-Hooks are run in a separate thread, isolated from the main. That means it is a
-different [realm](https://tc39.es/ecma262/#realm). The hooks thread may be
-terminated by the main thread at any time, so do not depend on asynchronous
-operations (like `console.log`) to complete.
+Hooks are run in a separate thread, isolated from the main thread where
+application code runs. That means it is a different [realm][]. The hooks thread
+may be terminated by the main thread at any time, so do not depend on
+asynchronous operations (like `console.log`) to complete.
#### `initialize()`
@@ -318,16 +383,14 @@ operations (like `console.log`) to complete.
added: REPLACEME
-->
-> The loaders API is being redesigned. This hook may disappear or its
-> signature may change. Do not rely on the API described below.
+> Stability: 1.1 - Active development
* `data` {any} The data from `register(loader, import.meta.url, { data })`.
* Returns: {any} The data to be returned to the caller of `register`.
-The `initialize` hook provides a way to define a custom function that runs
-in the loader's thread when the loader is initialized. Initialization happens
-when the loader is registered via [`register`][] or registered via the
-`--experimental-loader` command line option.
+The `initialize` hook provides a way to define a custom function that runs in
+the hooks thread when the hooks module is initialized. Initialization happens
+when the hooks module is registered via [`register`][].
This hook can send and receive data from a [`register`][] invocation, including
ports and other transferrable objects. The return value of `initialize` must be
@@ -338,11 +401,10 @@ either:
[`port.postMessage`][]),
* a `Promise` resolving to one of the aforementioned values.
-Loader code:
+Module customization code:
```mjs
-// In the below example this file is referenced as
-// '/path-to-my-loader.js'
+// path-to-my-hooks.js
export async function initialize({ number, port }) {
port.postMessage(`increment: ${number + 1}`);
@@ -357,16 +419,16 @@ import assert from 'node:assert';
import { register } from 'node:module';
import { MessageChannel } from 'node:worker_threads';
-// This example showcases how a message channel can be used to
-// communicate between the main (application) thread and the loader
-// running on the loaders thread, by sending `port2` to the loader.
+// This example showcases how a message channel can be used to communicate
+// between the main (application) thread and the hooks running on the hooks
+// thread, by sending `port2` to the `initialize` hook.
const { port1, port2 } = new MessageChannel();
port1.on('message', (msg) => {
assert.strictEqual(msg, 'increment: 2');
});
-const result = register('/path-to-my-loader.js', {
+const result = register('./path-to-my-hooks.js', {
parentURL: import.meta.url,
data: { number: 1, port: port2 },
transferList: [port2],
@@ -375,6 +437,30 @@ const result = register('/path-to-my-loader.js', {
assert.strictEqual(result, 'ok');
```
+```cjs
+const assert = require('node:assert');
+const { register } = require('node:module');
+const { pathToFileURL } = require('node:url');
+const { MessageChannel } = require('node:worker_threads');
+
+// This example showcases how a message channel can be used to communicate
+// between the main (application) thread and the hooks running on the hooks
+// thread, by sending `port2` to the `initialize` hook.
+const { port1, port2 } = new MessageChannel();
+
+port1.on('message', (msg) => {
+ assert.strictEqual(msg, 'increment: 2');
+});
+
+const result = register('./path-to-my-hooks.js', {
+ parentURL: pathToFileURL(__filename),
+ data: { number: 1, port: port2 },
+ transferList: [port2],
+});
+
+assert.strictEqual(result, 'ok');
+```
+
#### `resolve(specifier, context, nextResolve)`
-> The loaders API is being redesigned. This hook may disappear or its
-> signature may change. Do not rely on the API described below.
+> Stability: 1.2 - Release candidate
* `specifier` {string}
* `context` {Object}
@@ -417,21 +502,21 @@ changes:
terminate the chain of `resolve` hooks. **Default:** `false`
* `url` {string} The absolute URL to which this input resolves
-> **Caveat** Despite support for returning promises and async functions, calls
+> **Warning** Despite support for returning promises and async functions, calls
> to `resolve` may block the main thread which can impact performance.
The `resolve` hook chain is responsible for telling Node.js where to find and
-how to cache a given `import` statement or expression. It can optionally return
-its format (such as `'module'`) as a hint to the `load` hook. If a format is
-specified, the `load` hook is ultimately responsible for providing the final
-`format` value (and it is free to ignore the hint provided by `resolve`); if
-`resolve` provides a `format`, a custom `load` hook is required even if only to
-pass the value to the Node.js default `load` hook.
+how to cache a given `import` statement or expression, or `require` call. It can
+optionally return a format (such as `'module'`) as a hint to the `load` hook. If
+a format is specified, the `load` hook is ultimately responsible for providing
+the final `format` value (and it is free to ignore the hint provided by
+`resolve`); if `resolve` provides a `format`, a custom `load` hook is required
+even if only to pass the value to the Node.js default `load` hook.
Import type assertions are part of the cache key for saving loaded modules into
-the internal module cache. The `resolve` hook is responsible for
-returning an `importAssertions` object if the module should be cached with
-different assertions than were present in the source code.
+the internal module cache. The `resolve` hook is responsible for returning an
+`importAssertions` object if the module should be cached with different
+assertions than were present in the source code.
The `conditions` property in `context` is an array of conditions for
[package exports conditions][Conditional exports] that apply to this resolution
@@ -445,7 +530,7 @@ Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
`context.conditions` array originally passed into the `resolve` hook.
```mjs
-export function resolve(specifier, context, nextResolve) {
+export async function resolve(specifier, context, nextResolve) {
const { parentURL = null } = context;
if (Math.random() > 0.5) { // Some condition.
@@ -490,11 +575,7 @@ changes:
its return.
-->
-> The loaders API is being redesigned. This hook may disappear or its
-> signature may change. Do not rely on the API described below.
-
-> In a previous version of this API, this was split across 3 separate, now
-> deprecated, hooks (`getFormat`, `getSource`, and `transformSource`).
+> Stability: 1.2 - Release candidate
* `url` {string} The URL returned by the `resolve` chain
* `context` {Object}
@@ -512,8 +593,8 @@ changes:
terminate the chain of `resolve` hooks. **Default:** `false`
* `source` {string|ArrayBuffer|TypedArray} The source for Node.js to evaluate
-The `load` hook provides a way to define a custom method of determining how
-a URL should be interpreted, retrieved, and parsed. It is also in charge of
+The `load` hook provides a way to define a custom method of determining how a
+URL should be interpreted, retrieved, and parsed. It is also in charge of
validating the import assertion.
The final value of `format` must be one of the following:
@@ -529,19 +610,23 @@ The final value of `format` must be one of the following:
The value of `source` is ignored for type `'builtin'` because currently it is
not possible to replace the value of a Node.js builtin (core) module.
-The value of `source` can be omitted for type `'commonjs'`. When a `source` is
-provided, all `require` calls from this module will be processed by the ESM
-loader with registered `resolve` and `load` hooks; all `require.resolve` calls
-from this module will be processed by the ESM loader with registered `resolve`
-hooks; `require.extensions` and monkey-patching on the CommonJS module loader
-will not apply. If `source` is undefined or `null`, it will be handled by the
-CommonJS module loader and `require`/`require.resolve` calls will not go through
-the registered hooks. This behavior for nullish `source` is temporary — in the
-future, nullish `source` will not be supported.
-
-The Node.js own `load` implementation, which is the value of `next` for the last
-loader in the `load` chain, returns `null` for `source` when `format` is
-`'commonjs'` for backward compatibility. Here is an example loader that would
+Omitting vs providing a `source` for `'commonjs'` has very different effects:
+
+* When a `source` is provided, all `require` calls from this module will be
+ processed by the ESM loader with registered `resolve` and `load` hooks; all
+ `require.resolve` calls from this module will be processed by the ESM loader
+ with registered `resolve` hooks; only a subset of the CommonJS API will be
+ available (e.g. no `require.extensions`, no `require.cache`, no
+ `require.resolve.paths`) and monkey-patching on the CommonJS module loader
+ will not apply.
+* If `source` is undefined or `null`, it will be handled by the CommonJS module
+ loader and `require`/`require.resolve` calls will not go through the
+ registered hooks. This behavior for nullish `source` is temporary — in the
+ future, nullish `source` will not be supported.
+
+The Node.js internal `load` implementation, which is the value of `next` for the
+last hook in the `load` chain, returns `null` for `source` when `format` is
+`'commonjs'` for backward compatibility. Here is an example hook that would
opt-in to using the non-default behavior:
```mjs
@@ -556,7 +641,7 @@ export async function load(url, context, nextLoad) {
}
```
-> **Caveat**: The ESM `load` hook and namespaced exports from CommonJS modules
+> **Warning**: The ESM `load` hook and namespaced exports from CommonJS modules
> are incompatible. Attempting to use them together will result in an empty
> object from the import. This may be addressed in the future.
@@ -569,9 +654,9 @@ If the source value of a text-based format (i.e., `'json'`, `'module'`)
is not a string, it is converted to a string using [`util.TextDecoder`][].
The `load` hook provides a way to define a custom method for retrieving the
-source code of an ES module specifier. This would allow a loader to potentially
-avoid reading files from disk. It could also be used to map an unrecognized
-format to a supported one, for example `yaml` to `module`.
+source code of a resolved URL. This would allow a loader to potentially avoid
+reading files from disk. It could also be used to map an unrecognized format to
+a supported one, for example `yaml` to `module`.
```mjs
export async function load(url, context, nextLoad) {
@@ -611,11 +696,11 @@ changes:
description: Add support for chaining globalPreload hooks.
-->
-> This hook will be removed in a future version. Use [`initialize`][] instead.
-> When a loader has an `initialize` export, `globalPreload` will be ignored.
+> Stability: 1.0 - Early development
-> In a previous version of this API, this hook was named
-> `getGlobalPreloadCode`.
+> **Warning:** This hook will be removed in a future version. Use
+> [`initialize`][] instead. When a hooks module has an `initialize` export,
+> `globalPreload` will be ignored.
* `context` {Object} Information to assist the preload code
* `port` {MessagePort}
@@ -647,16 +732,17 @@ const require = createRequire(cwd() + '/');
}
```
-In order to allow communication between the application and the loader, another
-argument is provided to the preload code: `port`. This is available as a
-parameter to the loader hook and inside of the source text returned by the hook.
-Some care must be taken in order to properly call [`port.ref()`][] and
+Another argument is provided to the preload code: `port`. This is available as a
+parameter to the hook and inside of the source text returned by the hook. This
+functionality has been moved to the `initialize` hook.
+
+Care must be taken in order to properly call [`port.ref()`][] and
[`port.unref()`][] to prevent a process from being in a state where it won't
close normally.
```mjs
/**
- * This example has the application context send a message to the loader
+ * This example has the application context send a message to the hook
* and sends the message back to the application context
*/
export function globalPreload({ port }) {
@@ -664,7 +750,7 @@ export function globalPreload({ port }) {
port.postMessage(evt.data);
};
return `\
- port.postMessage('console.log("I went to the Loader and back");');
+ port.postMessage('console.log("I went to the hook and back");');
port.onmessage = (evt) => {
eval(evt.data);
};
@@ -674,22 +760,23 @@ export function globalPreload({ port }) {
### Examples
-The various loader hooks can be used together to accomplish wide-ranging
-customizations of the Node.js code loading and evaluation behaviors.
+The various module customization hooks can be used together to accomplish
+wide-ranging customizations of the Node.js code loading and evaluation
+behaviors.
-#### HTTPS loader
+#### Import from HTTPS
In current Node.js, specifiers starting with `https://` are experimental (see
[HTTPS and HTTP imports][]).
-The loader below registers hooks to enable rudimentary support for such
+The hook below registers hooks to enable rudimentary support for such
specifiers. While this may seem like a significant improvement to Node.js core
-functionality, there are substantial downsides to actually using this loader:
+functionality, there are substantial downsides to actually using these hooks:
performance is much slower than loading files from disk, there is no caching,
and there is no security.
```mjs
-// https-loader.mjs
+// https-hooks.mjs
import { get } from 'node:https';
export function load(url, context, nextLoad) {
@@ -724,59 +811,42 @@ import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffee
console.log(VERSION);
```
-With the preceding loader, running
-`node --experimental-loader ./https-loader.mjs ./main.mjs`
+With the preceding hooks module, running
+`node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./https-hooks.mjs"));' ./main.mjs`
prints the current version of CoffeeScript per the module at the URL in
`main.mjs`.
-#### Transpiler loader
+#### Transpilation
Sources that are in formats Node.js doesn't understand can be converted into
JavaScript using the [`load` hook][load hook].
-This is less performant than transpiling source files before running
-Node.js; a transpiler loader should only be used for development and testing
-purposes.
+This is less performant than transpiling source files before running Node.js;
+transpiler hooks should only be used for development and testing purposes.
```mjs
-// coffeescript-loader.mjs
+// coffeescript-hooks.mjs
import { readFile } from 'node:fs/promises';
import { dirname, extname, resolve as resolvePath } from 'node:path';
import { cwd } from 'node:process';
import { fileURLToPath, pathToFileURL } from 'node:url';
-import CoffeeScript from 'coffeescript';
+import coffeescript from 'coffeescript';
-const baseURL = pathToFileURL(`${cwd()}/`).href;
+const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;
export async function load(url, context, nextLoad) {
if (extensionsRegex.test(url)) {
- // Now that we patched resolve to let CoffeeScript URLs through, we need to
- // tell Node.js what format such URLs should be interpreted as. Because
- // CoffeeScript transpiles into JavaScript, it should be one of the two
- // JavaScript formats: 'commonjs' or 'module'.
-
// CoffeeScript files can be either CommonJS or ES modules, so we want any
// CoffeeScript file to be treated by Node.js the same as a .js file at the
// same location. To determine how Node.js would interpret an arbitrary .js
// file, search up the file system for the nearest parent package.json file
// and read its "type" field.
const format = await getPackageType(url);
- // When a hook returns a format of 'commonjs', `source` is ignored.
- // To handle CommonJS files, a handler needs to be registered with
- // `require.extensions` in order to process the files with the CommonJS
- // loader. Avoiding the need for a separate CommonJS handler is a future
- // enhancement planned for ES module loaders.
- if (format === 'commonjs') {
- return {
- format,
- shortCircuit: true,
- };
- }
const { source: rawSource } = await nextLoad(url, { ...context, format });
// This hook converts CoffeeScript source code into JavaScript source code
// for all imported CoffeeScript files.
- const transformedSource = coffeeCompile(rawSource.toString(), url);
+ const transformedSource = coffeescript.compile(rawSource.toString(), url);
return {
format,
@@ -833,23 +903,22 @@ console.log "Brought to you by Node.js version #{version}"
export scream = (str) -> str.toUpperCase()
```
-With the preceding loader, running
-`node --experimental-loader ./coffeescript-loader.mjs main.coffee`
+With the preceding hooks module, running
+`node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./coffeescript-hooks.mjs"));' ./main.coffee`
causes `main.coffee` to be turned into JavaScript after its source code is
loaded from disk but before Node.js executes it; and so on for any `.coffee`,
`.litcoffee` or `.coffee.md` files referenced via `import` statements of any
loaded file.
-#### "import map" loader
+#### Import maps
-The previous two loaders defined `load` hooks. This is an example of a loader
-that does its work via the `resolve` hook. This loader reads an
-`import-map.json` file that specifies which specifiers to override to another
-URL (this is a very simplistic implemenation of a small subset of the
-"import maps" specification).
+The previous two examples defined `load` hooks. This is an example of a
+`resolve` hook. This hooks module reads an `import-map.json` file that defines
+which specifiers to override to other URLs (this is a very simplistic
+implementation of a small subset of the "import maps" specification).
```mjs
-// import-map-loader.js
+// import-map-hooks.js
import fs from 'node:fs/promises';
const { imports } = JSON.parse(await fs.readFile('import-map.json'));
@@ -863,7 +932,7 @@ export async function resolve(specifier, context, nextResolve) {
}
```
-Let's assume we have these files:
+With these files:
```mjs
// main.js
@@ -884,19 +953,8 @@ import 'a-module';
console.log('some module!');
```
-If you run `node --experimental-loader ./import-map-loader.js main.js`
-the output will be `some module!`.
-
-### Register loaders programmatically
-
-
-
-In addition to using the `--experimental-loader` option in the CLI,
-loaders can also be registered programmatically. You can find
-detailed information about this process in the documentation page
-for [`module.register()`][].
+Running `node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./import-map-hooks.js"));' main.js`
+should print `some module!`.
## Source map v3 support
@@ -1044,9 +1102,11 @@ returned object contains the following keys:
[CommonJS]: modules.md
[Conditional exports]: packages.md#conditional-exports
+[Customization hooks]: #customization-hooks
[ES Modules]: esm.md
[HTTPS and HTTP imports]: esm.md#https-and-http-imports
[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
+[`"exports"`]: packages.md#exports
[`--enable-source-maps`]: cli.md#--enable-source-maps
[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
[`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir
@@ -1055,7 +1115,6 @@ returned object contains the following keys:
[`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
[`initialize`]: #initialize
-[`module.register()`]: #moduleregisterspecifier-parenturl-options
[`module`]: modules.md#the-module-object
[`port.postMessage`]: worker_threads.md#portpostmessagevalue-transferlist
[`port.ref()`]: worker_threads.md#portref
@@ -1066,5 +1125,6 @@ returned object contains the following keys:
[hooks]: #customization-hooks
[load hook]: #loadurl-context-nextload
[module wrapper]: modules.md#the-module-wrapper
+[realm]: https://tc39.es/ecma262/#realm
[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
[transferrable objects]: worker_threads.md#portpostmessagevalue-transferlist