@dual-bundle/import-meta-resolve
v4.1.0
Published
A fork of `import-meta-resolve` with commonjs + ESM support at the same time, AKA dual package.
Downloads
6,364,621
Maintainers
Readme
@dual-bundle/import-meta-resolve
A fork of import-meta-resolve
with commonjs + ESM support at the same time, AKA dual package.
It will rebase and try to release in order to sync with the upstream every day, see .github/workflows/rebase.yml for details.
Installation
# npm
npm install @dual-bundle/import-meta-resolve
# yarn
yarn add @dual-bundle/import-meta-resolve
import-meta-resolve
Resolve things like Node.js.
Contents
- What is this?
- When to use this?
- Install
- Use
- API
- Algorithm
- Differences to Node
- Types
- Compatibility
- Contribute
- License
What is this?
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!
When to use this?
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.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install import-meta-resolve
Use
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
API
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
).
Parameters
specifier
(string
) — the module specifier to resolve relative to parent (/example.js
,./example.js
,../example.js
,some-package
,fs
, etc)parent
(string
, example:import.meta.url
) — the absolute parent module URL to resolve from; you must passimport.meta.url
or something else
Returns
Full file:
, data:
, or node:
URL (string
) to the found thing
Throws
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
).
Parameters
specifier
(string
) —/example.js
,./example.js
,../example.js
,some-package
,fs
, etcparent
(URL
, example:import.meta.url
) — full URL (to a file) thatspecifier
is resolved relative fromconditions
(Set<string>
, default:new Set(['node', 'import'])
) — conditionspreserveSymlinks
(boolean
, default:false
) — keep symlinks instead of resolving them
Returns
A URL object (URL
) to the found thing.
Throws
Throws an ErrnoException
.
ErrnoException
One of many different errors that occur when resolving (TypeScript type).
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'
— whenspecifier
is invalid (example:'#'
)'ERR_INVALID_PACKAGE_CONFIG'
— when apackage.json
is invalid (example: invalid JSON)'ERR_INVALID_PACKAGE_TARGET'
— when apackage.json
exports
orimports
is invalid (example: when it does not start with'./'
)'ERR_MODULE_NOT_FOUND'
— whenspecifier
cannot be found inparent
(example:'some-missing-package'
)'ERR_NETWORK_IMPORT_DISALLOWED'
— thrown when trying to resolve a local file or builtin from a remote file (node:fs
relative to'https://example.com'
)'ERR_PACKAGE_IMPORT_NOT_DEFINED'
— when a local import is not defined in an import map (example:'#local'
when not defined)'ERR_PACKAGE_PATH_NOT_EXPORTED'
— when an export is not defined in an export map (example:'tape/index.js'
, which is not in its export map)'ERR_UNSUPPORTED_DIR_IMPORT'
— when attempting to import a directory (example:'./lib/'
)'ERR_UNKNOWN_FILE_EXTENSION'
— when somehow reading a file that has an unexpected extensions ('./readme.md'
)'ERR_INVALID_ARG_VALUE'
— whenconditions
is incorrect
Algorithm
The 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
).
Differences to Node
parent
defaulting toimport.meta.url
cannot be ponyfilled: you have to explicitly pass it- no support for loaders (that would mean implementing all of loaders)
- no support for CLI flags:
--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
work - no support for
WATCH_REPORT_DEPENDENCIES
env variable - no attempt is made to add a suggestion based on how things used to work in CJS before to not-found errors
- prototypal methods are not guarded: Node protects for example
String#slice
or so from being tampered with, whereas this doesn’t
Types
This package is fully typed with TypeScript.
It exports the additional type ErrnoException
.
Compatibility
This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 16 and later.
Contribute
Yes please! See How to Contribute to Open Source.
License
MIT © Titus Wormer and Node.js contributors