• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Modules: `module` API
2
3<!--introduced_in=v0.3.7-->
4
5## The `Module` object
6
7* {Object}
8
9Provides general utility methods when interacting with instances of
10`Module`, the [`module`][] variable often seen in [CommonJS][] modules. Accessed
11via `import 'module'` or `require('module')`.
12
13### `module.builtinModules`
14<!-- YAML
15added:
16  - v9.3.0
17  - v8.10.0
18  - v6.13.0
19-->
20
21* {string[]}
22
23A list of the names of all modules provided by Node.js. Can be used to verify
24if a module is maintained by a third party or not.
25
26`module` in this context isn't the same object that's provided
27by the [module wrapper][]. To access it, require the `Module` module:
28
29```js
30// module.mjs
31// In an ECMAScript module
32import { builtinModules as builtin } from 'module';
33```
34
35```js
36// module.cjs
37// In a CommonJS module
38const builtin = require('module').builtinModules;
39```
40
41### `module.createRequire(filename)`
42<!-- YAML
43added: v12.2.0
44-->
45
46* `filename` {string|URL} Filename to be used to construct the require
47  function. Must be a file URL object, file URL string, or absolute path
48  string.
49* Returns: {require} Require function
50
51```js
52import { createRequire } from 'module';
53const require = createRequire(import.meta.url);
54
55// sibling-module.js is a CommonJS module.
56const siblingModule = require('./sibling-module');
57```
58
59### `module.createRequireFromPath(filename)`
60<!-- YAML
61added: v10.12.0
62deprecated: v12.2.0
63-->
64
65> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead.
66
67* `filename` {string} Filename to be used to construct the relative require
68  function.
69* Returns: {require} Require function
70
71```js
72const { createRequireFromPath } = require('module');
73const requireUtil = createRequireFromPath('../src/utils/');
74
75// Require `../src/utils/some-tool`
76requireUtil('./some-tool');
77```
78
79### `module.syncBuiltinESMExports()`
80<!-- YAML
81added: v12.12.0
82-->
83
84The `module.syncBuiltinESMExports()` method updates all the live bindings for
85builtin [ES Modules][] to match the properties of the [CommonJS][] exports. It
86does not add or remove exported names from the [ES Modules][].
87
88```js
89const fs = require('fs');
90const { syncBuiltinESMExports } = require('module');
91
92fs.readFile = null;
93
94delete fs.readFileSync;
95
96fs.newAPI = function newAPI() {
97  // ...
98};
99
100syncBuiltinESMExports();
101
102import('fs').then((esmFS) => {
103  assert.strictEqual(esmFS.readFile, null);
104  assert.strictEqual('readFileSync' in fs, true);
105  assert.strictEqual(esmFS.newAPI, undefined);
106});
107```
108
109## Source map v3 support
110<!-- YAML
111added:
112 - v13.7.0
113 - v12.17.0
114-->
115
116> Stability: 1 - Experimental
117
118Helpers for interacting with the source map cache. This cache is
119populated when source map parsing is enabled and
120[source map include directives][] are found in a modules' footer.
121
122To enable source map parsing, Node.js must be run with the flag
123[`--enable-source-maps`][], or with code coverage enabled by setting
124[`NODE_V8_COVERAGE=dir`][].
125
126```js
127// module.mjs
128// In an ECMAScript module
129import { findSourceMap, SourceMap } from 'module';
130```
131
132```js
133// module.cjs
134// In a CommonJS module
135const { findSourceMap, SourceMap } = require('module');
136```
137
138### `module.findSourceMap(path[, error])`
139<!-- YAML
140added:
141 - v13.7.0
142 - v12.17.0
143-->
144
145* `path` {string}
146* `error` {Error}
147* Returns: {module.SourceMap}
148
149`path` is the resolved path for the file for which a corresponding source map
150should be fetched.
151
152The `error` instance should be passed as the second parameter to `findSourceMap`
153in exceptional flows, such as when an overridden
154[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
155the module cache until they are successfully loaded. In these cases, source maps
156are associated with the `error` instance along with the `path`.
157
158### Class: `module.SourceMap`
159<!-- YAML
160added:
161 - v13.7.0
162 - v12.17.0
163-->
164
165#### `new SourceMap(payload)`
166
167* `payload` {Object}
168
169Creates a new `sourceMap` instance.
170
171`payload` is an object with keys matching the [Source map v3 format][]:
172
173* `file`: {string}
174* `version`: {number}
175* `sources`: {string[]}
176* `sourcesContent`: {string[]}
177* `names`: {string[]}
178* `mappings`: {string}
179* `sourceRoot`: {string}
180
181#### `sourceMap.payload`
182
183* Returns: {Object}
184
185Getter for the payload used to construct the [`SourceMap`][] instance.
186
187#### `sourceMap.findEntry(lineNumber, columnNumber)`
188
189* `lineNumber` {number}
190* `columnNumber` {number}
191* Returns: {Object}
192
193Given a line number and column number in the generated source file, returns
194an object representing the position in the original file. The object returned
195consists of the following keys:
196
197* generatedLine: {number}
198* generatedColumn: {number}
199* originalSource: {string}
200* originalLine: {number}
201* originalColumn: {number}
202
203[CommonJS]: modules.html
204[ES Modules]: esm.html
205[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
206[`SourceMap`]: #module_class_module_sourcemap
207[`createRequire()`]: #module_module_createrequire_filename
208[`module`]: modules.html#modules_the_module_object
209[module wrapper]: modules_cjs.html#modules_cjs_the_module_wrapper
210[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
211[`--enable-source-maps`]: cli.html#cli_enable_source_maps
212[`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir
213[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
214