Repository navigation
Fall back to a user-configured directory when resolving imports #67354
Description
What is the problem this feature will solve?
Node.js doesn't support a user-configured fallback directory when trying to resolve imports. It only resolves those imports against a node_modules directory in the same (or ancestor) directory as the importing file. This current architecture falls short for standalone scripts, which don't have a node_modules directory around.
This artificial limitation hinders Node.js's ability to fulfill its goal to "Run JavaScript Everywhere".
What is the feature you are proposing to solve the problem?
Fall back to a user-configured directory when normal resolution fails
What alternatives have you considered?
- Hardcoding absolute paths using the
file://protocol- fragile
- not portable
- A symlinked
node_modulesin the importing file's directory- overridden once
npm installis executed
- overridden once
- A symlinked
node_modulesin a shared ancestor directory- must be located at the filesystem root to cover every location
- A register hook that retries from a specified directory after an
ERR_MODULE_NOT_FOUND/MODULE_NOT_FOUNDerror- must be included in every importing file
- doesn't work with static imports
- isn't compatible with tooling (e.g., IDEs don't run it, so they treat the imported modules like unresolved ones)
Activity
ljharb commentedon Nov 9, 2026
This is a very intentional design choice. CJS has a deprecated env var for this, and it's proven to be a horrifically terrible idea to make the location of modules configurable, which is why ESM explicitly avoids doing so.
Standalone scripts can use SEA to package up a bundled file into a single executable; that's the path I'd suggest.
cos4ni2s commentedon Nov 10, 2026
And also a limitation that causes dependency duplication (reinstalling the same dependencies for each project) and friction (setting up a project and populating a
node_modulesdirectory for the simplest tasks).Runtimes for many mainstream languages (Python, Ruby, Java, PHP, C#, ...) support user-configurable locations. What's so horrible about it?
A single executable application:
import()to load modules from the filesystem,A simple script file requires none of this
ljharb commentedon Nov 10, 2026
Yep, that's true. but once you add dependencies, you need a way to package them. A single folder containing a script with
node_modulesandpackage.jsonis a lot easier to manage, and a lot more portable, than an arbitrary location.It is a limitation - but a beneficial one. Dependency duplication is a feature, not a bug, and it's why npm/cargo/nix are the only non-broken package ecosystems in existence. As for friction, that's unavoidable if you have dependencies - if you want no friction, then you'd need to avoid having any dependencies.