unjsexsolve
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 exsolveImport:
// 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:
resolveModuleURLreturns a URL string likefile:///app/dep.mjs.resolveModulePathreturns an absolute path like/app/dep.mjs.- If the resolved URL does not use the
file://scheme (e.g.,data:ornode:), it will throw an error.
- If the resolved URL does not use the
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
exportsfield inpackage.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
/indexwhen 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
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.