Resolve things like Node.js — ponyfill for `import.meta.resolve`
OTHER License
Resolve things like Node.js.
This package is a ponyfill for import.meta.resolve
.
It supports everything you need to resolve files just like modern Node does:
import maps, export maps, loading CJS and ESM projects, all of that!
As of Node.js 20.0, import.meta.resolve
is still behind an experimental flag.
This package can be used to do what it does in Node 16–20.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install import-meta-resolve
import {resolve} from 'import-meta-resolve'
// A file:
console.log(resolve('./index.js', import.meta.url))
//=> file:///Users/tilde/Projects/oss/import-meta-resolve/index.js
// A CJS package:
console.log(resolve('builtins', import.meta.url))
//=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/builtins/index.js
// A scoped CJS package:
console.log(resolve('@eslint/eslintrc', import.meta.url))
//=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/@eslint/eslintrc/lib/index.js
// A package with an export map:
console.log(resolve('micromark/lib/parse', import.meta.url))
//=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/micromark/lib/parse.js
// A node builtin:
console.log(resolve('fs', import.meta.url))
//=> node:fs
This package exports the identifiers moduleResolve
and
resolve
.
There is no default export.
resolve(specifier, parent)
Match import.meta.resolve
except that parent
is required (you can pass
import.meta.url
).
specifier
(string
)/example.js
, ./example.js
, ../example.js
, some-package
, fs
, etc)parent
(string
, example: import.meta.url
)import.meta.url
or something elseFull file:
, data:
, or node:
URL (string
) to the found thing
Throws an ErrnoException
.
moduleResolve(specifier, parent, conditions, preserveSymlinks)
The “Resolver Algorithm Specification” as detailed in the Node docs
(which is slightly lower-level than resolve
).
specifier
(string
)/example.js
, ./example.js
, ../example.js
, some-package
, fs
, etcparent
(URL
, example: import.meta.url
)specifier
is resolved relative fromconditions
(Set<string>
, default: new Set(['node', 'import'])
)preserveSymlinks
(boolean
, default: false
)A URL object (URL
) to the found thing.
Throws an ErrnoException
.
ErrnoException
One of many different errors that occur when resolving (TypeScript type).
type ErrnoExceptionFields = Error & {
errnode?: number | undefined
code?: string | undefined
path?: string | undefined
syscall?: string | undefined
url?: string | undefined
}
The code
field on errors is one of the following strings:
'ERR_INVALID_MODULE_SPECIFIER'
specifier
is invalid (example: '#'
)'ERR_INVALID_PACKAGE_CONFIG'
package.json
is invalid (example: invalid JSON)'ERR_INVALID_PACKAGE_TARGET'
package.json
exports
or imports
is invalid (example: when it'./'
)'ERR_MODULE_NOT_FOUND'
specifier
cannot be found in parent
(example: 'some-missing-package'
)'ERR_NETWORK_IMPORT_DISALLOWED'
node:fs
relative to 'https://example.com'
)'ERR_PACKAGE_IMPORT_NOT_DEFINED'
'#local'
'ERR_PACKAGE_PATH_NOT_EXPORTED'
'tape/index.js'
,'ERR_UNSUPPORTED_DIR_IMPORT'
'./lib/'
)'ERR_UNKNOWN_FILE_EXTENSION'
'./readme.md'
)'ERR_INVALID_ARG_VALUE'
conditions
is incorrectThe algorithm for resolve
matches how Node handles import.meta.resolve
, with
a couple of differences.
The algorithm for moduleResolve
matches the Resolver Algorithm
Specification as detailed in the Node docs (which is sync and slightly
lower-level than resolve
).
parent
defaulting to import.meta.url
cannot be ponyfilled: you have to--conditions
,--experimental-default-type
,--experimental-json-modules
,--experimental-network-imports
,--experimental-policy
,--experimental-wasm-modules
,--input-type
,--no-addons
,--preserve-symlinks
, nor--preserve-symlinks-main
WATCH_REPORT_DEPENDENCIES
env variableString#slice
This package is fully typed with TypeScript.
It exports the additional type ErrnoException
.
This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 16 and later.
Yes please! See How to Contribute to Open Source.
MIT © Titus Wormer and Node.js contributors