import-meta-resolve

Resolve things like Node.js. Ponyfill for import.meta.resolve. Supports import maps, export maps, loading CJS and ESM projects, all of that!

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install import-meta-resolve

Use

import {resolve} from 'import-meta-resolve'

main()

async function main() {
  // A file:
  console.log(await resolve('./index.js', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/index.js

  // A CJS package:
  console.log(await resolve('builtins', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/builtins/index.js

  // A scoped CJS package:
  console.log(await resolve('@babel/core', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/@babel/core/lib/index.js

  // A package with an export map:
  console.log(await resolve('tape/lib/test', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/tape/lib/test.js
}

API

This package exports the following identifiers: resolve, moduleResolve. There is no default export.

`resolve(specifier, parent)`

Match import.meta.resolve except that parent is required (you should probably pass import.meta.url).

Parameters

specifier (string) — /example.js, ./example.js, ../example.js, some-package
parent (string, example: import.meta.url) Full URL (to a file) that specifier is resolved relative from

Returns

Returns a promise that resolves to a full file:, data:, or node: URL to the found thing.

`moduleResolve(specifier, parent[, conditions])`

The “Resolver Algorithm Specification” as detailed in the Node docs (which is sync and slightly lower-level than resolve).

Parameters

specifier (string) — /example.js, ./example.js, ../example.js, some-package
parent (URL, example: import.meta.url) Full URL (to a file) that specifier is resolved relative from
conditions (Set<string>, default: new Set('node', 'import')) Conditions

Returns

A URL object to the found thing.

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 to import.meta.url cannot be ponyfilled: you have to explicitly pass it
No support for CLI flags: --experimental-specifier-resolution, --experimental-json-modules, --experimental-wasm-modules, --experimental-policy, --input-type, --preserve-symlinks, --preserve-symlinks-main, nor --conditions work
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

Errors

ERR_INVALID_MODULE_SPECIFIER — when specifier is invalid
ERR_INVALID_PACKAGE_CONFIG — when a package.json is invalid
ERR_INVALID_PACKAGE_TARGET — when a package.json exports or imports is invalid
ERR_MODULE_NOT_FOUND — when specifier cannot be found in parent
ERR_PACKAGE_IMPORT_NOT_DEFINED — when a local import is not defined in an import map
ERR_PACKAGE_PATH_NOT_EXPORTED — when an export is not defined in an export map
ERR_UNSUPPORTED_DIR_IMPORT — when attempting to import a directory

License

Current Tags

2.1.0 ... latest (3 years ago)

2 Versions

2.1.0 ... 3 years ago
1.1.1 ... 4 years ago