Commit add1184
doc: clarify require behavior with non .js extensions
Refs: https://github.com/nodejs/node/discussions/41333
PR-URL: #41345
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>1 parent b5b3750 commit add1184
1 file changed
Lines changed: 18 additions & 9 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -133,10 +133,13 @@ relative, and based on the real path of the files making the calls to | |||
| 133 | 133 | ||
| 134 | 134 | ## The `.mjs` extension | |
| 135 | 135 | ||
| 136 | - It is not possible to `require()` files that have the `.mjs` extension. | ||
| 137 | - Attempting to do so will throw [an error][]. The `.mjs` extension is | ||
| 138 | - reserved for [ECMAScript Modules][] which cannot be loaded via `require()`. | ||
| 139 | - See [ECMAScript Modules][] for more details. | ||
| 136 | + Due to the synchronous nature of `require()`, it is not possible to use it to | ||
| 137 | + load ECMAScript module files. Attempting to do so will throw a | ||
| 138 | + [`ERR_REQUIRE_ESM`][] error. Use [`import()`][] instead. | ||
| 139 | + | ||
| 140 | + The `.mjs` extension is reserved for [ECMAScript Modules][] which cannot be | ||
| 141 | + loaded via `require()`. See [Determining module system][] section for more info | ||
| 142 | + regarding which files are parsed as ECMAScript modules. | ||
| 140 | 143 | ||
| 141 | 144 | ## All together... | |
| 142 | 145 | ||
@@ -373,11 +376,15 @@ correctly within an application. | |||
| 373 | 376 | ||
| 374 | 377 | If the exact filename is not found, then Node.js will attempt to load the | |
| 375 | 378 | required filename with the added extensions: `.js`, `.json`, and finally | |
| 376 | - `.node`. | ||
| 379 | + `.node`. When loading a file that has a different extension (e.g. `.cjs`), its | ||
| 380 | + full name must be passed to `require()`, including its file extension (e.g. | ||
| 381 | + `require('./file.cjs')`). | ||
| 377 | 382 | ||
| 378 | - `.js` files are interpreted as JavaScript text files, and `.json` files are | ||
| 379 | - parsed as JSON text files. `.node` files are interpreted as compiled addon | ||
| 380 | - modules loaded with `process.dlopen()`. | ||
| 383 | + `.json` files are parsed as JSON text files, `.node` files are interpreted as | ||
| 384 | + compiled addon modules loaded with `process.dlopen()`. Files using any other | ||
| 385 | + extension (or no extension at all) are parsed as JavaScript text files. Refer to | ||
| 386 | + the [Determining module system][] section to understand what parse goal will be | ||
| 387 | + used. | ||
| 381 | 388 | ||
| 382 | 389 | A required module prefixed with `'/'` is an absolute path to the file. For | |
| 383 | 390 | example, `require('/home/marco/foo.js')` will load the file at | |
@@ -1032,19 +1039,21 @@ This section was moved to | |||
| 1032 | 1039 | * <a id="modules_sourcemap_payload" href="module.html#sourcemappayload">`sourceMap.payload`</a> | |
| 1033 | 1040 | * <a id="modules_sourcemap_findentry_linenumber_columnnumber" href="module.html#sourcemapfindentrylinenumber-columnnumber">`sourceMap.findEntry(lineNumber, columnNumber)`</a> | |
| 1034 | 1041 | ||
| 1042 | + [Determining module system]: packages.md#determining-module-system | ||
| 1035 | 1043 | [ECMAScript Modules]: esm.md | |
| 1036 | 1044 | [GLOBAL_FOLDERS]: #loading-from-the-global-folders | |
| 1037 | 1045 | [`"main"`]: packages.md#main | |
| 1046 | + [`ERR_REQUIRE_ESM`]: errors.md#err_require_esm | ||
| 1038 | 1047 | [`Error`]: errors.md#class-error | |
| 1039 | 1048 | [`__dirname`]: #__dirname | |
| 1040 | 1049 | [`__filename`]: #__filename | |
| 1050 | + [`import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports | ||
| 1041 | 1051 | [`module.children`]: #modulechildren | |
| 1042 | 1052 | [`module.id`]: #moduleid | |
| 1043 | 1053 | [`module` object]: #the-module-object | |
| 1044 | 1054 | [`package.json`]: packages.md#nodejs-packagejson-field-definitions | |
| 1045 | 1055 | [`path.dirname()`]: path.md#pathdirnamepath | |
| 1046 | 1056 | [`require.main`]: #requiremain | |
| 1047 | - [an error]: errors.md#err_require_esm | ||
| 1048 | 1057 | [exports shortcut]: #exports-shortcut | |
| 1049 | 1058 | [module resolution]: #all-together | |
| 1050 | 1059 | [native addons]: addons.md | |
0 commit comments