Improve module.createRequire documentation

Is your feature request related to a problem? Please describe.
The documentation was unclear for createRequire, I see #27758 & #27762 made a change and adds import.meta.url. I think this change adds difficulty (and needs more information) to understand this example.

Also, the filename argument (path) can be a file, or URL. I don't understand why ../src/utils/ was changed to import.meta.url. It makes no sense to use createRequire with the module URL. And why rewrite "require" ?

Describe the solution you'd like

Rewrite the example :

import { createRequire } from 'module';
const requireUtil = createRequire(require.resolve('../src/utils/'));

// Require `../src/utils/some-tool`
requireUtil('./some-tool');

Describe alternatives you've considered
Another solution was: Add explain before the example and a link to https://nodejs.org/api/esm.html#esm_import_meta

Second part :

Is your feature request related to a problem? Please describe.
The documentation was unclear for createRequire. I think the argument name path is more suited to filename in module.createRequire(filename) According to : "Must be a file URL object, file URL string, or absolute path string."

Describe the solution you'd like
Change filename to path.

It makes no sense to use createRequire with the module URL. And why rewrite "require" ?

As stated in another documentation page, require is not available on the global scope of a ES modules. This example is not to rewrite require, but to create it. Using the module URL allows ES modules to use require the same way CJS files can.

Also I think there is an error in the example code in the issue description:

> node test.js
./test.js:1
import { createRequire } from "module";
       ^

SyntaxError: Unexpected token {
    at Module._compile (internal/modules/cjs/loader.js:720:23)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:787:10)
    at Module.load (internal/modules/cjs/loader.js:643:32)
    at Function.Module._load (internal/modules/cjs/loader.js:556:12)
    at Function.Module.runMain (internal/modules/cjs/loader.js:839:10)
    at internal/main/run_main_module.js:17:11

import syntax is not supported outside of ES2015 modules, so this code doesn't work in CJS mode.

> node --experimental-modules test.mjs
(node:15432) ExperimentalWarning: The ESM module loader is experimental.
file:///.../test.mjs:2
const requireUtil = createRequire(require.resolve("../src/utils/"));
                                  ^

ReferenceError: require is not defined
    at file:///.../test.mjs:2:35
    at ModuleJob.run (internal/modules/esm/module_job.js:111:37)

require is not defined, so this code doesn't work in ESM mode.

IMHO that would probably be clearer to add an example using CJS, even though the function is more intended for ESM.

The import.meta.url means a context for the new require from the createRequire?

From fix cli imports PR

const createRequireConstructor = isAbsolute(from) ? from : resolve(from);
const relativeRequire = createRequire(createRequireConstructor); // here

import.meta.url refers to the URL of the current module. When you pass it to createRequire, it is indeed used for context to create the require function.

I think it's time to close this 2-year-old issue, anyone would be very welcome to open a PR to update createRequire documentation if they think it can be improved, and feel free to re-open / to continue the discussion here if you want.

Navigation Menu

Repository navigation

Improve module.createRequire documentation #28730

Second part :

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Improve module.createRequire documentation #28730

Description

Second part :

Activity

aduh95 commented on Jul 26, 2019

vanpipy commented on Mar 4, 2022

aduh95 commented on Mar 4, 2022

aduh95 commented on Mar 4, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions