exsolve

exsolve

Module resolution utilities for Node.js (based on previous work in unjs/mlly, wooorm/import-meta-resolve, and the upstream Node.js implementation).

This library exposes an API similar to import.meta.resolve based on Node.js's upstream implementation and resolution algorithm. It supports all built-in functionalities—import maps, export maps, CJS, and ESM—with some additions:

• Pure JS with no native dependencies (only Node.js is required).
• Built-in resolve cache.
• Throws an error (or try) if the resolved path does not exist in the filesystem.
• Can override the default conditions.
• Can resolve from one or more parent URLs.
• Can resolve with custom suffixes.
• Can resolve with custom extensions.

Usage

Install the package:

# ✨ Auto-detect (npm, yarn, pnpm, bun, deno)
npx nypm install exsolve

Import:

// ESM import
import { resolveModuleURL, resolveModulePath, createResolver, clearResolveCache } from "exsolve";

// Or using dynamic import
const { resolveModulePath } = await import("exsolve");

resolveModuleURL(id, {/* options */});

resolveModulePath(id, {/* options */});

Differences between resolveModuleURL and resolveModulePath:

• resolveModuleURL returns a URL string like file:///app/dep.mjs.
• resolveModulePath returns an absolute path like /app/dep.mjs.
  • If the resolved URL does not use the file:// scheme (e.g., data: or node:), it will throw an error.

Resolver with Options

You can create a custom resolver instance with default options using createResolver.

Example:

import { createResolver } from "exsolve";

const { resolveModuleURL, resolveModulePath } = createResolver({
  suffixes: ["", "/index"],
  extensions: [".mjs", ".cjs", ".js", ".mts", ".cts", ".ts", ".json"],
  conditions: ["node", "import", "production"],
});

Resolve Cache

To speed up resolution, resolved values (and errors) are globally cached with a unique key based on id and options (and the current working directory, when from is missing or relative). Each cache hit for an error throws a new copy.

Parsed package.json files are cached along with the resolve cache that read them: clearing it (with clearResolveCache(), a resolver's clearResolveCache() or cache.clear()) or passing a new cache object also reads them again, and with cache: false they are only reused within a single call.

Example: Invalidate all (global) cache entries (to support file-system changes).

import { clearResolveCache } from "exsolve";

clearResolveCache();

Example: Custom resolver with custom cache object.

import { createResolver } from "exsolve";

const { clearResolveCache, resolveModulePath } = createResolver({
  cache: new Map(),
});

Example: Resolve without cache.

import { resolveModulePath } from "exsolve";

resolveModulePath("id", { cache: false });

Resolve Options

try

If set to true and the module cannot be resolved, the resolver returns undefined instead of throwing an error.

Example:

// undefined
const resolved = resolveModuleURL("non-existing-package", { try: true });

from

A URL, path, or array of URLs/paths from which to resolve the module.

If not provided, resolution starts from the current working directory. Setting this option is recommended.

You can use import.meta.url for from to mimic the behavior of import.meta.resolve().

[!TIP] For better performance, ensure the value is a file:// URL or at least ends with /.

If it is set to an absolute path, the resolver must first check the filesystem to see if it is a file or directory. If the input is a file:// URL or ends with /, the resolver can skip this check.

conditions

Conditions to apply when resolving package exports (default: ["node", "import"]).

Example:

// "/app/src/index.ts"
const src = resolveModuleURL("pkg-name", {
  conditions: ["deno", "node", "import", "production"],
});

[!NOTE] Conditions are applied without order. The order is determined by the exports field in package.json.

extensions

Additional file extensions to check as fallbacks.

Example:

// "/app/src/index.ts"
const src = resolveModulePath("./src/index", {
  extensions: [".mjs", ".cjs", ".js", ".mts", ".cts", ".ts", ".json"],
});

[!TIP] For better performance, use explicit extensions and avoid this option.

suffixes

Path suffixes to check.

Example:

// "/app/src/utils/index.ts"
const src = resolveModulePath("./src/utils", {
  suffixes: ["", "/index"],
  extensions: [".mjs", ".cjs", ".js"],
});

[!TIP] For better performance, use explicit /index when needed and avoid this option.

preserveSymlinks

If set to true, symlinks are not resolved to their real path (similar to Node.js --preserve-symlinks).

Example:

// file:///path/to/link.mjs (instead of the symlink target)
const resolved = resolveModuleURL("./link.mjs", { from: import.meta.url, preserveSymlinks: true });

cache

Resolve cache (enabled by default with a shared global object).

Can be set to false to disable or a custom Map to bring your own cache object.

See cache for more info.

Other Performance Tips

Use explicit module extensions .mjs or .cjs instead of .js:

This allows the resolution fast path to skip reading the closest package.json for the type.

Development

local development

• Clone this repository
• Install the latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Published under the MIT license.

Based on previous work in unjs/mlly, wooorm/import-meta-resolve and Node.js original implementation.

Similar packages

Other packages similar to exsolve

resolve

A widely used package implementing Node.js-style module resolution. It offers a familiar resolution model and sync and async APIs; exsolve is another option with a lightweight utility-oriented API.

resolve-from

Resolves a module as though it were required from a specified directory. It is a focused alternative when resolving a package from a particular location; exsolve also provides path-resolution utilities.

enhanced-resolve

A configurable resolver used by tools such as webpack. It supports extensive hooks and customization, making it more feature-rich for bundler use; exsolve is generally a simpler choice for common Node.js resolution tasks.

import-meta-resolve

Provides module resolution based on the ESM import.meta.resolve semantics. It is useful when matching ESM resolution behavior specifically, while exsolve offers a broader set of convenient resolution utilities.