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.

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.

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.