Is it legal to modify `module.paths`?

[hopeless-programmer-online]

• Node.js Version:
  v.13.12.0
• OS:
  Windows 7
• Scope (install, code, runtime, meta, other?):
  Runtime/docs.
• Module (and version) (if relevant):
  module.paths.

Docs are not very helpful, since they do not clarify is this property mutable or not.

It is important, because changing this variable actually leads to changes in the behavior of require function.
So it would be good if someone make it clear what kind of usage this property supports and intended to.

Basically, the following code works just fine:

const path = require(`path`);

// adding path to `lol` directory, which contains `kek.js` file
module.paths.unshift( path.join(__dirname, `lol`) );

// require works, despite `kek` is not inside of any of `node_modules` directories
const kek = require("kek");

console.log(kek);

But should it work at all?
It hard to say from the docs.

Please, advise. Thanks.

[lundibundi]

I don't think it's good/worth to change it even though the docs don't explicitly prohibit it, you can see relevant docs at modules#loading_from_the_global_folders which has a similar idea.

What is your use case? Why isn't it possible to just explicitly specify a path to the module?

[hopeless-programmer-online]

@lundibundi
I have no specific use cases. I am just writing an article on this topic and want to clarify the expected behavior.

I think it is extremely important to explicitly state (im)mutability of such basic APIs. This will make a clear border between illegal (with possible undefined behavior) and legal but possibly rare usages (with fully defined behavior).

[lundibundi]

Well, the original property was added more than 9 years ago (nodejs/node@4651348) and was undocumented up until 3 years ago nodejs/node#14435.

I think it is extremely important to explicitly state (im)mutability of such basic APIs. This will make a clear border between illegal (with possible undefined behavior) and legal but possibly rare usages (with fully defined behavior).

Yeah, if that was an API added now it would definitely be better documented and stated its mutability but at this point it more of an it-was-there-from-the-beginning and it not gonna go away so at least document it. From that point in time, a lot has changed especially since we "Node.js ecosystem has settled on a convention for locating dependent modules". The part of the doc on global folders somewhat touches current concerns/state of it.

So to sum it up, yes it is public documented API so you can use it (including changing) but whether you should is whole another question. My personal answer would be 'no unless you are absolutely sure you need it'.

[gireeshpunathil]

answered, closing. feel free to re-open if it is outstanding

[david-morris]

I have a nested project and I've noticed that if the outer project's node_modules is present, the inner project will not build or run.

This appears to have to do with module resolution issues.

I'm using storybook in a project, which depends on `@mdx-js/react@2.3.0`, while the child folder is docusaurus and depends on `@mdx-js/react@1.6.22`.

[WARNING] {"moduleIdentifier":"/workspaces/react/.docusaurus/node_modules/babel-loader/lib/index.js??ruleSet[1].rules[8].use[0]!/workspaces/react/.docusaurus/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[8].use[1]!/workspaces/react/.docusaurus/node_modules/@docusaurus/plugin-content-docs/lib/markdown/index.js??ruleSet[1].rules[8].use[2]!/workspaces/react/.docs/overview/storybook.md","moduleName":"../.docs/overview/storybook.md","loc":"14:231-234","message":"export 'mdx' (imported as 'mdx') was not found in '@mdx-js/react' (possible exports: MDXContext, MDXProvider, useMDXComponents, withMDXComponents)","compilerPath":"server"}

One of my dependencies is importing this (I don't have an explicit import anywhere) so I can't force the resolution path. And I'm stumped why it chooses the parent folder version anyway; maybe something was digging around for a specific symbol?)

Therefore, I wish to strike the parent project's node_modules from module.paths.

Should this be reopened? Is there a better API to make node submodule projects resolve their own modules all the time, even if that means giving up on a resolution/import?

Am I wrong in thinking that import paths should be configurable enough to nest projects?

Edited to add: changing module.paths in the entrypoint js file does not fix the problem, though it does affect what I can import in the REPL. I guess there's a routine that populates module.paths for every module, and I need to configure it globally somehow?

[ljharb]

No, that’s not a thing that should be easily possible.