diff --git a/doc/api/process.md b/doc/api/process.md index 1970caf82c0128..9e5483ea2c170b 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1921,6 +1921,46 @@ console.log('After:', getActiveResourcesInfo()); // After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ] ``` +## `process.getBuiltinModule(id)` + + + +* `id` {string} ID of the built-in module being requested. +* Returns: {Object|undefined} + +`process.getBuiltinModule(id)` provides a way to load built-in modules +in a globally available function. ES Modules that need to support +other environments can use it to conditionally load a Node.js built-in +when it is run in Node.js, without having to deal with the resolution +error that can be thrown by `import` in a non-Node.js environment or +having to use dynamic `import()` which either turns the module into +an asynchronous module, or turns a synchronous API into an asynchronous one. + +```mjs +if (globalThis.process?.getBuiltinModule) { + // Run in Node.js, use the Node.js fs module. + const fs = globalThis.process.getBuiltinModule('fs'); + // If `require()` is needed to load user-modules, use createRequire() + const module = globalThis.process.getBuiltinModule('module'); + const require = module.createRequire(import.meta.url); + const foo = require('foo'); +} +``` + +If `id` specifies a built-in module available in the current Node.js process, +`process.getBuiltinModule(id)` method returns the corresponding built-in +module. If `id` does not correspond to any built-in module, `undefined` +is returned. + +`process.getBuiltinModule(id)` accepts built-in module IDs that are recognized +by [`module.isBuiltin(id)`][]. Some built-in modules must be loaded with the +`node:` prefix, see [built-in modules with mandatory `node:` prefix][]. +The references returned by `process.getBuiltinModule(id)` always point to +the built-in module corresponding to `id` even if users modify +[`require.cache`][] so that `require(id)` returns something else. + ## `process.getegid()`