Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve module.createRequire documentation #28730

Closed
A-312 opened this issue Jul 17, 2019 · 4 comments
Closed

Improve module.createRequire documentation #28730

A-312 opened this issue Jul 17, 2019 · 4 comments
Labels
doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem.

Comments

@A-312
Copy link

A-312 commented Jul 17, 2019

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.

@A-312 A-312 closed this as completed Jul 17, 2019
@A-312 A-312 reopened this Jul 17, 2019
@aduh95
Copy link
Contributor

aduh95 commented Jul 26, 2019

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.

@targos targos added doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem. labels Dec 26, 2020
@vanpipy
Copy link

vanpipy commented Mar 4, 2022

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

@aduh95
Copy link
Contributor

aduh95 commented Mar 4, 2022

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.

@aduh95
Copy link
Contributor

aduh95 commented Mar 4, 2022

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.

@aduh95 aduh95 closed this as completed Mar 4, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem.
Projects
None yet
Development

No branches or pull requests

4 participants