Rspack resolver

Rust port of enhanced-resolve.

• 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
• supports in-memory file system via the FileSystem trait
• supports Yarn's Plug'n'Play
• contains tracing instrumentation

Usage

Basic npm usage

Use the opinionated synchronous resolver with default options:

import * as resolver from '@rspack/resolver';

// Use the opinionated sync resolver with default options
const { path: resolvedPath } = resolver.sync(contextPath, './index.js');

// When resolution fails
const result = resolver.sync(contextPath, './noExist.js');
// result => { error: "Cannot find module './noExist.js'" }

There's also an equivalent async API:

import * as resolver from '@rspack/resolver';

// Use the opinionated sync resolver with default options
const { path: resolvedPath } = await resolver.async(contextPath, './index.js');

Custom resolver with options

You can customize the resolver using ResolverFactory:

import { ResolverFactory } from '@rspack/resolver';

const resolver = new ResolverFactory(resolveOptions);

// Sync API
const result = resolver.sync(contextPath, './request.js');
// result => { path: "/the/resolved/path/index.js" }
//        or { error: "Cannot find module './request.js'" }

// Async API
const result = await resolver.async(contextPath, './request.js');
// result => { path: "/the/resolved/path/index.js" }
//        or { error: "Cannot find module './request.js'" }

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)

5. 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).

Errors & trouble shooting

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

Options

The options are aligned with enhanced-resolve.

Other options

• string []: relative path (based on directory of the referencing tsconfig file) or absolute path of referenced project's tsconfig | | enablePnp | false | Enable Yarn Plug'n'Play support |

In the context of @rspack/resolver, the tsconfig.references option helps isolate the paths configurations of different TypeScript projects. This ensures that path aliases defined in one TypeScript project do not unintentionally affect the resolving behavior of another.

Given the following project structure:

├── app
│   ├── mock_foo
│   │   ├── index.js
│   │   └── package.json
│   ├── package.json
│   ├── src
│   │   └── index.ts
│   ├── tsconfig.json
│   └── webpack.config.js
└── component
    ├── index.js
    ├── mock_foo
    │   ├── index.js
    │   └── package.json
    ├── package.json
    ├── src
    │   └── index.ts
    └── tsconfig.json

• Both app and component have their own tsconfig.json.
• Each defines a path alias foo pointing to their respective mock_foo directory.
• app/tsconfig.json includes component as a referenced project.

When configuring @rspack/resolver with app/tsconfig.json, the resolving result for import foo in component/src/index.ts differs based on whether tsconfig.references is enabled:

Unimplemented options

[!NOTE]
Rspack-resolver is a fork of oxc-resolver, maintained specifically for use in Rspack.

While it originated from oxc-resolver, we decided to maintain a fork because Rspack requires a different file system API. This ensures better alignment with Rspack’s design and long-term stability, while still benefiting from the foundation laid by oxc-resolver.