1# Modules: `node:module` API 2 3<!--introduced_in=v12.20.0--> 4 5<!-- YAML 6added: v0.3.7 7--> 8 9## The `Module` object 10 11* {Object} 12 13Provides general utility methods when interacting with instances of 14`Module`, the [`module`][] variable often seen in [CommonJS][] modules. Accessed 15via `import 'node:module'` or `require('node:module')`. 16 17### `module.builtinModules` 18 19<!-- YAML 20added: 21 - v9.3.0 22 - v8.10.0 23 - v6.13.0 24--> 25 26* {string\[]} 27 28A list of the names of all modules provided by Node.js. Can be used to verify 29if a module is maintained by a third party or not. 30 31`module` in this context isn't the same object that's provided 32by the [module wrapper][]. To access it, require the `Module` module: 33 34```mjs 35// module.mjs 36// In an ECMAScript module 37import { builtinModules as builtin } from 'node:module'; 38``` 39 40```cjs 41// module.cjs 42// In a CommonJS module 43const builtin = require('node:module').builtinModules; 44``` 45 46### `module.createRequire(filename)` 47 48<!-- YAML 49added: v12.2.0 50--> 51 52* `filename` {string|URL} Filename to be used to construct the require 53 function. Must be a file URL object, file URL string, or absolute path 54 string. 55* Returns: {require} Require function 56 57```mjs 58import { createRequire } from 'node:module'; 59const require = createRequire(import.meta.url); 60 61// sibling-module.js is a CommonJS module. 62const siblingModule = require('./sibling-module'); 63``` 64 65### `module.isBuiltin(moduleName)` 66 67<!-- YAML 68added: v18.6.0 69--> 70 71* `moduleName` {string} name of the module 72* Returns: {boolean} returns true if the module is builtin else returns false 73 74```mjs 75import { isBuiltin } from 'node:module'; 76isBuiltin('node:fs'); // true 77isBuiltin('fs'); // true 78isBuiltin('wss'); // false 79``` 80 81### `module.syncBuiltinESMExports()` 82 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('node:fs'); 93const assert = require('node:assert'); 94const { syncBuiltinESMExports } = require('node:module'); 95 96fs.readFile = newAPI; 97 98delete fs.readFileSync; 99 100function newAPI() { 101 // ... 102} 103 104fs.newAPI = newAPI; 105 106syncBuiltinESMExports(); 107 108import('node: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 122<!-- YAML 123added: 124 - v13.7.0 125 - v12.17.0 126--> 127 128> Stability: 1 - Experimental 129 130Helpers for interacting with the source map cache. This cache is 131populated when source map parsing is enabled and 132[source map include directives][] are found in a modules' footer. 133 134To enable source map parsing, Node.js must be run with the flag 135[`--enable-source-maps`][], or with code coverage enabled by setting 136[`NODE_V8_COVERAGE=dir`][]. 137 138```mjs 139// module.mjs 140// In an ECMAScript module 141import { findSourceMap, SourceMap } from 'node:module'; 142``` 143 144```cjs 145// module.cjs 146// In a CommonJS module 147const { findSourceMap, SourceMap } = require('node:module'); 148``` 149 150<!-- Anchors to make sure old links find a target --> 151 152<a id="module_module_findsourcemap_path_error"></a> 153 154### `module.findSourceMap(path)` 155 156<!-- YAML 157added: 158 - v13.7.0 159 - v12.17.0 160--> 161 162* `path` {string} 163* Returns: {module.SourceMap|undefined} Returns `module.SourceMap` if a source 164 map is found, `undefined` otherwise. 165 166`path` is the resolved path for the file for which a corresponding source map 167should be fetched. 168 169### Class: `module.SourceMap` 170 171<!-- YAML 172added: 173 - v13.7.0 174 - v12.17.0 175--> 176 177#### `new SourceMap(payload)` 178 179* `payload` {Object} 180 181Creates a new `sourceMap` instance. 182 183`payload` is an object with keys matching the [Source map v3 format][]: 184 185* `file`: {string} 186* `version`: {number} 187* `sources`: {string\[]} 188* `sourcesContent`: {string\[]} 189* `names`: {string\[]} 190* `mappings`: {string} 191* `sourceRoot`: {string} 192 193#### `sourceMap.payload` 194 195* Returns: {Object} 196 197Getter for the payload used to construct the [`SourceMap`][] instance. 198 199#### `sourceMap.findEntry(lineOffset, columnOffset)` 200 201* `lineOffset` {number} The zero-indexed line number offset in 202 the generated source 203* `columnOffset` {number} The zero-indexed column number offset 204 in the generated source 205* Returns: {Object} 206 207Given a line offset and column offset in the generated source 208file, returns an object representing the SourceMap range in the 209original file if found, or an empty object if not. 210 211The object returned contains the following keys: 212 213* generatedLine: {number} The line offset of the start of the 214 range in the generated source 215* generatedColumn: {number} The column offset of start of the 216 range in the generated source 217* originalSource: {string} The file name of the original source, 218 as reported in the SourceMap 219* originalLine: {number} The line offset of the start of the 220 range in the original source 221* originalColumn: {number} The column offset of start of the 222 range in the original source 223* name: {string} 224 225The returned value represents the raw range as it appears in the 226SourceMap, based on zero-indexed offsets, _not_ 1-indexed line and 227column numbers as they appear in Error messages and CallSite 228objects. 229 230To get the corresponding 1-indexed line and column numbers from a 231lineNumber and columnNumber as they are reported by Error stacks 232and CallSite objects, use `sourceMap.findOrigin(lineNumber, 233columnNumber)` 234 235#### `sourceMap.findOrigin(lineNumber, columnNumber)` 236 237* `lineNumber` {number} The 1-indexed line number of the call 238 site in the generated source 239* `columnOffset` {number} The 1-indexed column number 240 of the call site in the generated source 241* Returns: {Object} 242 243Given a 1-indexed lineNumber and columnNumber from a call site in 244the generated source, find the corresponding call site location 245in the original source. 246 247If the lineNumber and columnNumber provided are not found in any 248source map, then an empty object is returned. Otherwise, the 249returned object contains the following keys: 250 251* name: {string | undefined} The name of the range in the 252 source map, if one was provided 253* fileName: {string} The file name of the original source, as 254 reported in the SourceMap 255* lineNumber: {number} The 1-indexed lineNumber of the 256 corresponding call site in the original source 257* columnNumber: {number} The 1-indexed columnNumber of the 258 corresponding call site in the original source 259 260[CommonJS]: modules.md 261[ES Modules]: esm.md 262[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej 263[`--enable-source-maps`]: cli.md#--enable-source-maps 264[`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir 265[`SourceMap`]: #class-modulesourcemap 266[`module`]: modules.md#the-module-object 267[module wrapper]: modules.md#the-module-wrapper 268[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx 269