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