Registry / http-networking / esm-resolve

esm-resolve

library1.0.11jsnpmunverified

esm-resolve is a synchronous ESM import resolver for Node.js, designed to be used within development servers or build processes. Currently at version 1.0.11, it offers a stable and permissive approach to module resolution. Key differentiators include its pure JavaScript implementation, support for modern Node.js resolution features like subpath exports/imports and conditional exports, and a default behavior that rewrites to 'browser', 'import', or 'default' keys (rather than 'node'). It was developed before `import.meta.resolve()` was widely available and aims to provide a more permissive resolution experience. The library is designed to fail gracefully and also handles the removal of imports pointing purely to `.d.ts` files, simplifying TypeScript workflows. While it doesn't specify a strict release cadence, its 1.x versioning suggests a mature and stable library.

http-networking devops web-framework

npm install esm-resolve

github ↗package ↗

INSTALL

IMPORT

SIG · ESM-RESOLVE

esm-resolve

http-networkingjavascriptv1.0.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

buildResolver

✓ import buildResolver from 'esm-resolve';

✗ const buildResolver = require('esm-resolve');

The library is ESM-first. CommonJS `require` is not supported for importing `esm-resolve` itself, though it helps resolve ESM imports.

{ buildResolver } (named import)

✓ import { buildResolver } from 'esm-resolve';

✗ import buildResolver from 'esm-resolve'; // when expecting named

Both default and named imports for `buildResolver` are shown as working in the README. Use the named import if your bundler or linter prefers it.

Resolver options (Type)

✓ import type { Options } from 'esm-resolve/types/external';

For type-checking configuration options, import `Options` from the specific types path.

This quickstart demonstrates how to initialize `esm-resolve` with `buildResolver`, perform basic relative and package resolutions, and configure the resolver for Node.js-specific behaviors and `.mjs` file matching using options like `constraints` and `matchNakedMjs`.

import buildResolver from 'esm-resolve'; import path from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // Create a resolver based on the importing file. Relative paths are resolved correctly. const resolver = buildResolver(path.join(__dirname, 'src', 'main.js')); console.log(`Resolving './relative': ${resolver('./relative')}`); // Expected: './relative.js' (relative to the importer, not process.cwd()) console.log(`Resolving 'lodash': ${resolver('lodash')}`); // Expected: e.g., '../node_modules/lodash/lodash.js' or similar package entry // Configure the resolver for Node.js-specific constraints and .mjs support const nodeResolver = buildResolver(path.join(__dirname, 'src', 'server.js'), { constraints: 'node', matchNakedMjs: true, }); console.log(`Resolving './foo' with node constraints (if 'foo.mjs' exists): ${nodeResolver('./foo')}`); console.log(`Resolving 'some-node-only-pkg' with node constraints: ${nodeResolver('some-node-only-pkg')}`);

Debug

Known issues

gotchaesm-resolve was developed before Node.js's native `import.meta.resolve()` was widely available and stable. While it offers a more permissive resolution, developers might consider `import.meta.resolve()` for simpler use cases to avoid additional dependencies, although `esm-resolve` handles more edge cases.

fix

Evaluate if native `import.meta.resolve()` (now synchronous in Node.js v20+) meets your needs, or if `esm-resolve`'s permissive and configurable features are required for your specific build or dev server scenario.

affects: >=1.0.0

gotchaBy default, `esm-resolve` prioritizes 'browser', 'import', or 'default' keys in package `exports` fields. This means it may not resolve paths correctly for Node.js-specific builds if the package's `exports` map defines a 'node' condition.

fix

If resolving for a Node.js environment, explicitly set the `constraints` option to `'node'` when calling `buildResolver`: `buildResolver(importer, { constraints: 'node' })`.

affects: >=1.0.0

gotchaThe resolved path returned by `esm-resolve` is relative to the *importer* file, not your process's current working directory (`process.cwd()`). This can be surprising if you expect absolute paths by default.

fix

To always receive an absolute path, set the `resolveToAbsolute` option to `true`: `buildResolver(importer, { resolveToAbsolute: true })`.

affects: >=1.0.0

gotcha`esm-resolve` is designed to be permissive and fails gracefully, including falling back to real paths if `exports` aren't defined. While this can prevent crashes, it might mask underlying package configuration issues that stricter resolvers would flag.

fix

Be aware of this behavior and thoroughly test your import resolutions, especially in production builds, to ensure that the permissive resolution doesn't hide misconfigurations that could cause problems in different environments or with other tools.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module '<module_name>'

The resolver failed to find a module, potentially due to default browser-oriented resolution conditions, even if a Node.js-specific export exists.

fix

If you are resolving in a Node.js environment, ensure you pass `{ constraints: 'node' }` to `buildResolver` to correctly match Node.js-specific `exports` conditions in `package.json`. Also, verify file extensions and subpath exports.

TypeError: buildResolver is not a function

`esm-resolve` is an ECMAScript Module (ESM) library. Attempting to import it using CommonJS `require()` syntax will fail in an ESM context or a `type: module` project.

fix

Ensure you are using ESM `import` statements: `import buildResolver from 'esm-resolve';` or `import { buildResolver } from 'esm-resolve';`. If your project uses CommonJS, you may need to configure your build system to handle ESM dependencies or reconsider the library choice.

Upgrade

Version history

1.0.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/samthor/esm-resolve ↗

packagehttps://www.npmjs.com/package/esm-resolve ↗