`require.resolve` regression starts from Node v12 with `paths`

[JounQin]

Version

v20.19.2

Platform

Darwin MacBookPro 24.5.0 Darwin Kernel Version 24.5.0: Tue Apr 22 19:54:49 PDT 2025; root:xnu-11417.121.6~2/RELEASE_ARM64_T6000 arm64

Subsystem

No response

What steps will reproduce the bug?

https://github.com/JounQin/test/tree/repro/node_require_resolve_paths

Simply run node test.js

On node 10:

`resolve` npm package: <CWD>/fixtures/bar.js
`require.resolve` built-in function: <CWD>/fixtures/bar.js

How often does it reproduce? Is there a required condition?

Persist

What is the expected behavior? Why is that the expected behavior?

There is a related old issue #29139.

What do you see instead?

On node 12+, of course including Node LTS (20+)

`resolve` npm package: /Users/JounQin/Workspaces/GitHub/test/fixtures/bar.js
node:internal/modules/cjs/loader:1404
  throw err;
  ^

Error: Cannot find module 'bar'
Require stack:
- <CWD>/test.js
    at Function._resolveFilename (node:internal/modules/cjs/loader:1401:15)
    at Function.resolve (node:internal/modules/helpers:145:19)
    at Object.<anonymous> (/Users/JounQin/Workspaces/GitHub/test/test.js:16:11)
    at Module._compile (node:internal/modules/cjs/loader:1730:14)
    at Object..js (node:internal/modules/cjs/loader:1895:10)
    at Module.load (node:internal/modules/cjs/loader:1465:32)
    at Function._load (node:internal/modules/cjs/loader:1282:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:171:5) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '<CWD>/test.js' ]
}

Additional information

I believe there is no reports because most projects use http://npmjs.com/resolve instead, and it behaviors same as Node 10-, and I'm trying to remove resolve as dependency, so I just met this issue at un-ts/eslint-plugin-import-x#272 (comment)

cc @cjihrig

[climba03003]

It doesn't look like a regression but intentional change from your linked issue.
require.resolve is aligned with placing a file inside the fixtures folder and require('bar').

The paths mean the starting point of module resolution, meaning the bar folder should place inside the node_modules folder to consider as module that can be required.

/
├── test.js
└── fixtures
     ├── bar.js # should be found by relative path "./bar.js" or "./bar"
     ├── bar # should be found by relative path "./bar" if "./bar.js" is not exist
     |    └── index.js
     └── node_modules
         └── bar # should be found by "bar"
             └── index.js

[JounQin]

@climba03003 What about fixtures/node_modules/bar.js with bar? It is actually preferred over fixtures/node_modules/bar/index.js on my testing.

/
├── test.js
└── fixtures
     ├── bar.js # should be found by relative path "./bar.js" or "./bar"
     ├── bar # should be found by relative path "./bar" if "./bar.js" is not exist
     |    └── index.js
     └── node_modules
         ├── bar.js # what about this one with "bar"?
         └── bar # should be found by "bar"
             └── index.js

[climba03003]

It indeed prefer file over directory from the algorithm.
package.json exports field > file > directory.

LOAD_NODE_MODULES(X, START)
1. let DIRS = NODE_MODULES_PATHS(START)
2. for each DIR in DIRS:
   a. LOAD_PACKAGE_EXPORTS(X, DIR)
   b. LOAD_AS_FILE(DIR/X)
   c. LOAD_AS_DIRECTORY(DIR/X)

The algorithm can be found https://nodejs.org/api/modules.html#all-together

[JounQin]

It indeed prefer file over directory from the algorithm.

So paths option works different with node_modules now.

[climba03003]

So paths option works different with node_modules now.

I didn't get it, but you can check the algorithm on the site.
Even verify if there is different when placing the file on the paths that require the require.resolve file.

On your repro, it doesn't seems there is a mismatch on behavior.

[JounQin]

paths is an option to override node_modules, so I'd expect when paths is specified it behaviors same as node_modules.

[climba03003]

paths is the options to consider as starting point (similar as working directory).
It is not stated as override the node_modules or use as node_modules.

Here is the description on the document.
Each of these paths is used as a starting point for the module resolution algorithm, meaning that the node_modules hierarchy is checked from this location.

Edit: Maybe the latter part is a bit misleading?

[JounQin]

Maybe the latter part is a bit misleading?

Yeah, that's the point I think.

[ljharb]

Certainly paths should represent "directories in which the require is performed from", not node_modules dirs.

If require.resolve with a single path in the paths option differs from require.resolve ran directly in that directory, then that would be a bug.

[JounQin]

Certainly paths should represent "directories in which the require is performed from", not node_modules dirs.

If require.resolve with a single path in the paths option differs from require.resolve ran directly in that directory, then that would be a bug.

@ljharb I tried the following on Node 10 and 12+:

// fixtures/foo.js

const resolve = require('resolve')

console.log(resolve('bar')) // undefined
console.log(require.resolve('bar')) // error

But with paths option enabled, resolve package works different with require.resolve starting from Node 12 as I mentioned in the issue content.

[ljharb]

If there’s a bug in the resolve package, please file it. This issue is about the paths option to require.resolve, though.

[JounQin]

If there’s a bug in the resolve package, please file it. This issue is about the paths option to require.resolve, though.

@ljharb I'm not saying there’s a bug in the resolve package, it seems behavioring same as Node itself when no paths enabled, but with paths, the resolve package follows Node 10- for all Node versions.

[ljharb]

Gotcha, that makes sense.