{"id":13151,"library":"esm-resolve","title":"ESM Import Resolver for Node.js","description":"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.","status":"active","version":"1.0.11","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/samthor/esm-resolve","tags":["javascript","typescript"],"install":[{"cmd":"npm install esm-resolve","lang":"bash","label":"npm"},{"cmd":"yarn add esm-resolve","lang":"bash","label":"yarn"},{"cmd":"pnpm add esm-resolve","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is ESM-first. CommonJS `require` is not supported for importing `esm-resolve` itself, though it helps resolve ESM imports.","wrong":"const buildResolver = require('esm-resolve');","symbol":"buildResolver","correct":"import buildResolver from 'esm-resolve';"},{"note":"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.","wrong":"import buildResolver from 'esm-resolve'; // when expecting named","symbol":"{ buildResolver } (named import)","correct":"import { buildResolver } from 'esm-resolve';"},{"note":"For type-checking configuration options, import `Options` from the specific types path.","symbol":"Resolver options (Type)","correct":"import type { Options } from 'esm-resolve/types/external';"}],"quickstart":{"code":"import buildResolver from 'esm-resolve';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Create a resolver based on the importing file. Relative paths are resolved correctly.\nconst resolver = buildResolver(path.join(__dirname, 'src', 'main.js'));\n\nconsole.log(`Resolving './relative': ${resolver('./relative')}`);\n// Expected: './relative.js' (relative to the importer, not process.cwd())\n\nconsole.log(`Resolving 'lodash': ${resolver('lodash')}`);\n// Expected: e.g., '../node_modules/lodash/lodash.js' or similar package entry\n\n// Configure the resolver for Node.js-specific constraints and .mjs support\nconst nodeResolver = buildResolver(path.join(__dirname, 'src', 'server.js'), {\n  constraints: 'node',\n  matchNakedMjs: true,\n});\n\nconsole.log(`Resolving './foo' with node constraints (if 'foo.mjs' exists): ${nodeResolver('./foo')}`);\nconsole.log(`Resolving 'some-node-only-pkg' with node constraints: ${nodeResolver('some-node-only-pkg')}`);\n","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"esm-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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If resolving for a Node.js environment, explicitly set the `constraints` option to `'node'` when calling `buildResolver`: `buildResolver(importer, { constraints: 'node' })`.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To always receive an absolute path, set the `resolveToAbsolute` option to `true`: `buildResolver(importer, { resolveToAbsolute: true })`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The resolver failed to find a module, potentially due to default browser-oriented resolution conditions, even if a Node.js-specific export exists.","error":"Error: Cannot find module '<module_name>'"},{"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.","cause":"`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.","error":"TypeError: buildResolver is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}