Home

Awesome

import-meta-resolve

Build Coverage Downloads

Resolve things like Node.js.

Contents

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
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
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:

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

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

<!-- Definitions -->