214 lines
6.0 KiB
Markdown
214 lines
6.0 KiB
Markdown
# exsolve
|
|
|
|
[](https://npmjs.com/package/exsolve)
|
|
[](https://npm.chart.dev/exsolve)
|
|
[](https://packagephobia.com/result?p=exsolve)
|
|
|
|
> Module resolution utilities for Node.js (based on previous work in [unjs/mlly](https://github.com/unjs/mlly), [wooorm/import-meta-resolve](https://github.com/wooorm/import-meta-resolve), and the upstream [Node.js](https://github.com/nodejs/node) implementation).
|
|
|
|
This library exposes an API similar to [`import.meta.resolve`](https://nodejs.org/api/esm.html#importmetaresolvespecifier) based on Node.js's upstream implementation and [resolution algorithm](https://nodejs.org/api/esm.html#esm_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](#resolve-cache).
|
|
- Throws an error (or [try](#try)) if the resolved path does not exist in the filesystem.
|
|
- Can override the default [conditions](#conditions).
|
|
- Can resolve [from](#from) one or more parent URLs.
|
|
- Can resolve with custom [suffixes](#suffixes).
|
|
- Can resolve with custom [extensions](#extensions).
|
|
|
|
## Usage
|
|
|
|
Install the package:
|
|
|
|
```sh
|
|
# ✨ Auto-detect (npm, yarn, pnpm, bun, deno)
|
|
npx nypm install exsolve
|
|
```
|
|
|
|
Import:
|
|
|
|
```ts
|
|
// ESM import
|
|
import {
|
|
resolveModuleURL,
|
|
resolveModulePath,
|
|
createResolver,
|
|
clearResolveCache,
|
|
} from "exsolve";
|
|
|
|
// Or using dynamic import
|
|
const { resolveModulePath } = await import("exsolve");
|
|
```
|
|
|
|
```ts
|
|
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](#resolve-options) using `createResolver`.
|
|
|
|
**Example:**
|
|
|
|
```ts
|
|
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).
|
|
|
|
```ts
|
|
import { clearResolveCache } from "exsolve";
|
|
|
|
clearResolveCache();
|
|
```
|
|
|
|
**Example:** Custom resolver with custom cache object.
|
|
|
|
```ts
|
|
import { createResolver } from "exsolve";
|
|
|
|
const { clearResolveCache, resolveModulePath } = createResolver({
|
|
cache: new Map(),
|
|
});
|
|
```
|
|
|
|
**Example:** Resolve without cache.
|
|
|
|
```ts
|
|
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:**
|
|
|
|
```ts
|
|
// 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:**
|
|
|
|
```ts
|
|
// "/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:**
|
|
|
|
```ts
|
|
// "/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:**
|
|
|
|
```ts
|
|
// "/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](#resolve-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`](https://nodejs.org/api/packages.html#type).
|
|
|
|
## Development
|
|
|
|
<details>
|
|
|
|
<summary>local development</summary>
|
|
|
|
- Clone this repository
|
|
- Install the latest LTS version of [Node.js](https://nodejs.org/en/)
|
|
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
|
|
- Install dependencies using `pnpm install`
|
|
- Run interactive tests using `pnpm dev`
|
|
|
|
</details>
|
|
|
|
## License
|
|
|
|
Published under the [MIT](https://github.com/unjs/exsolve/blob/main/LICENSE) license.
|
|
|
|
Based on previous work in [unjs/mlly](https://github.com/unjs/mlly), [wooorm/import-meta-resolve](https://github.com/wooorm/import-meta-resolve) and [Node.js](https://github.com/nodejs/node) original implementation.
|