27 releases (13 stable)

1.5.4 Feb 23, 2024
1.2.2 Jan 24, 2024
1.0.1 Dec 21, 2023
0.6.2 Dec 18, 2023
0.5.5 Nov 30, 2023

#1 in #esm

Download history 807/week @ 2023-11-12 802/week @ 2023-11-19 716/week @ 2023-11-26 1395/week @ 2023-12-03 1129/week @ 2023-12-10 1320/week @ 2023-12-17 1218/week @ 2023-12-24 915/week @ 2023-12-31 1012/week @ 2024-01-07 900/week @ 2024-01-14 1423/week @ 2024-01-21 1540/week @ 2024-01-28 896/week @ 2024-02-04 835/week @ 2024-02-11 2842/week @ 2024-02-18 2109/week @ 2024-02-25

6,797 downloads per month

MIT license

380KB
8K SLoC

OXC Logo

Crates.io Docs.rs

MIT licensed Build Status Code Coverage CodSpeed Badge Sponsors Discord chat

Oxc 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
  • supports in-memory file system via the FileSystem trait
  • contains tracing instrumentation

Usage

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 = ResolverFactory({
  conditionNames: ["node", "import"]
});

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

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"]
}

Options

The options are aligned with enhanced-resolve.

Field Default Description
alias [] A list of module alias configurations or an object which maps key to value
aliasFields [] A list of alias fields in description files
extensionAlias {} An object which maps extension to extension aliases
conditionNames [] A list of exports field condition names
descriptionFiles ["package.json"] A list of description files to read from
enforceExtension false Enforce that a extension from extensions must be used
exportsFields ["exports"] A list of exports fields in description files
extensions [".js", ".json", ".node"] A list of extensions which should be tried for files
fallback [] Same as alias, but only used if default resolving fails
fileSystem The file system which should be used
fullySpecified false Request passed to resolve is already fully specified and extensions or main files are not resolved for it (they are still resolved for internal requests)
mainFields ["main"] A list of main fields in description files
mainFiles ["index"] A list of main files in directories
modules ["node_modules"] A list of directories to resolve modules from, can be absolute path or folder name
resolveToContext false Resolve to a context instead of a file
preferRelative false Prefer to resolve module requests as relative request and fallback to resolving as module
preferAbsolute false Prefer to resolve server-relative urls as absolute paths before falling back to resolve in roots
restrictions [] A list of resolve restrictions
roots [] A list of root paths
symlinks true Whether to resolve symlinks to their symlinked location

Unimplemented Options

Field Default Description
cachePredicate function() { return true }; A function which decides whether a request should be cached or not. An object is passed to the function with path and request properties.
cacheWithContext true If unsafe cache is enabled, includes request.context in the cache key
plugins [] A list of additional resolve plugins which should be applied
resolver undefined A prepared Resolver to which the plugins are attached
unsafeCache false Use this cache object to unsafely cache the successful requests

Debugging

Rspack

The following environment variable will emit tracing information.

RSPACK_PROFILE='TRACE=filter=oxc_resolver=trace&layer=logger' rspack build

Test

Tests are ported from

Test cases are located in ./src/tests, fixtures are located in ./tests

  • alias.test.js
  • browserField.test.js
  • dependencies.test.js
  • exportsField.test.js
  • extension-alias.test.js
  • extensions.test.js
  • fallback.test.js
  • fullSpecified.test.js
  • identifier.test.js (see unit test in crates/oxc_resolver/src/request.rs)
  • importsField.test.js
  • incorrect-description-file.test.js (need to add ctx.fileDependencies)
  • missing.test.js
  • path.test.js (see unit test in crates/oxc_resolver/src/path.rs)
  • plugins.test.js
  • pnp.test.js
  • resolve.test.js
  • restrictions.test.js (partially done, regex is not supported yet)
  • roots.test.js
  • scoped-packages.test.js
  • simple.test.js
  • symlink.test.js

Irrelevant tests

  • CachedInputFileSystem.test.js
  • SyncAsyncFileSystemDecorator.test.js
  • forEachBail.test.js
  • getPaths.test.js
  • pr-53.test.js
  • unsafe-cache.test.js
  • yield.test.js

📖 License

oxc_resolver is free and open-source software licensed under the MIT License.

Oxc partially copies code from the following projects.

Project License
webpack/enhanced-resolve MIT
dividab/tsconfig-paths MIT
parcel-bundler/parcel MIT
tmccombs/json-comments-rs Apache 2.0

Dependencies

~2–13MB
~131K SLoC