<img alt="Oxc logo" src="https://oxc.rs/oxc-dark.svg" height="60">

[![Crates.io][crates-badge]][crates-url] [![npmjs.com][npm-badge]][npm-url]

[![Docs.rs][docs-badge]][docs-url] [![Build Status][ci-badge]][ci-url] [![Code Coverage][code-coverage-badge]][code-coverage-url] [![CodSpeed Badge][codspeed-badge]][codspeed-url] [![Sponsors][sponsors-badge]][sponsors-url] [![Discord chat][discord-badge]][discord-url] [![MIT licensed][license-badge]][license-url]

Oxc Resolver

Rust port of [enhanced-resolve], [tsconfig-paths-webpack-plugin] and [tsconfck]

• Released on crates.io and npm.
• Implements the ESM and CommonJS module resolution algorithm specification.
• Built-in [tsconfig-paths-webpack-plugin]
• support extending tsconfig defined in tsconfig.extends
• support paths alias defined in tsconfig.compilerOptions.paths
• support project references defined tsconfig.references
• support template variable ${configDir} for substitution of config files directory path
• Built-in tsconfig discovery ([tsconfck])
• Supports in-memory file system via the FileSystem trait.
• Contains tracing instrumentation.

Usage

npm package

See index.d.ts for resolveSync and ResolverFactory API.

Quick example:

import assert from "assert";
import path from "path";
import resolve, { ResolverFactory } from "./index.js";

// `resolve`
assert(resolve.sync(process.cwd(), "./index.js").path, path.join(cwd, "index.js"));

// `ResolverFactory`
const resolver = new ResolverFactory();
assert(resolver.sync(process.cwd(), "./index.js").path, path.join(cwd, "index.js"));

File-based Resolution

For file-based resolution with automatic tsconfig discovery, use resolveFileSync or resolveFileAsync:

const resolver = new ResolverFactory();

// Resolves from a file path (not directory)
const result = resolver.resolveFileSync("/path/to/file.ts", "./module");

// Async version
const result = await resolver.resolveFileAsync("/path/to/file.ts", "./module");

Key Differences:

• sync(directory, specifier) - Takes a directory path, uses manually configured tsconfig if provided
• resolveFileSync(file, specifier) - Takes a file path, automatically discovers tsconfig.json by traversing parent directories

Why use resolveFileSync?

When resolving from a specific file (e.g., in bundlers, linters, or language servers), resolveFileSync automatically finds the correct tsconfig.json by:

• Traversing parent directories from the file location
• Respecting TypeScript project references
• Honoring include, exclude, and files fields to determine which tsconfig applies
• Ensuring tsconfig paths aliases work correctly based on the file's context

Supports WASM

See https://stackblitz.com/edit/oxc-resolver for usage example.

Rust

See docs.rs/oxc_resolver.

Yarn Plug'n'Play

• For node.js, yarn pnp should work without any configuration, given the following conditions:
• the program is called with the yarn command, where the value process.versions.pnp is set.
• .pnp.cjs manifest file exists in the closest directory, searched from the current working directory,
• no multi-project setup, per second bullet point in FIND_PNP_MANIFEST

Terminology

directory

An absolute path to a directory where the specifier is resolved against.

For CommonJS modules, it is the __dirname variable that contains the absolute path to the folder containing current module.

For ECMAScript modules, it is the value of import.meta.url.

Behavior is undefined when given a path to a file.

specifier

The string passed to require or import, i.e. require("specifier") or import "specifier"

Errors and Trouble Shooting

• Error: Package subpath '.' is not defined by "exports" in - occurs when resolving without conditionNames.

Configuration

The following usages apply to both Rust and Node.js; the code snippets are written in JavaScript.

To handle the exports field in package.json, ESM and CJS need to be differentiated.

ESM

Per ESM Resolution algorithm

defaultConditions is the conditional environment name array, ["node", "import"].

This means when the caller is an ESM import (import "module"), resolve options should be

{
  "conditionNames": ["node", "import"]
}

CJS

Per CJS Resolution algorithm

LOAD_PACKAGE_EXPORTS(X, DIR)

1. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH, package.json "exports", ["node", "require"]) defined in the ESM resolver.

This means when the caller is a CJS require (require("module")), resolve options should be

{
  "conditionNames": ["node", "require"]
}

Cache

To support both CJS and ESM with the same cache:

const esmResolver = new ResolverFactory({
  conditionNames: ["node", "import"],
});

const cjsResolver = esmResolver.cloneWithOptions({
  conditionNames: ["node", "require"],
});

Browser Field

From this non-standard spec:

The browser field is provided to JavaScript bundlers or component tools when packaging modules for client side use.

The option is

{
  "aliasFields": ["browser"]
}

Main Field

{
  "mainFields": ["module", "main"]
}

Quoting esbuild's documentation:

• main - This is the standard field for all packages that are meant to be used with node. The name main is hard-coded in to node's module resolution logic itself. Because it's intended for use with node, it's reasonable to expect that the file path in this field is a CommonJS-style module.
• module - This field came from a proposal for how to integrate ECMAScript modules into node. Because of this, it's reasonable to expect that the file path in this field is an ECMAScript-style module. This proposal wasn't adopted by node (node uses "type": "module" instead) but it was adopted by major bundlers because ECMAScript-style modules lead to better tree shaking, or dead code removal.
• browser - This field came from a proposal that allows bundlers to replace node-specific files or modules with their browser-friendly versions. It lets you specify an alternate browser-specific entry point. Note that it is possible for a package to use both the browser and module field together (see the note below).

Options

The following options are aligned with [enhanced-resolve], and is implemented for Rust crate usage.

See index.d.ts for Node.js usage.

TypeScript Configuration

• string []: relative path (based on directory of the referencing tsconfig file) or absolute path of referenced project's tsconfig |

Unimplemented Options

| Field | Default