Crate oxc_resolver

Expand description

§Oxc Resolver

Node.js CommonJS and ECMAScript Module Resolution.

Released on crates.io and npm.

A module resolution is the process of finding the file referenced by a module specifier in import "specifier" or require("specifier").

All configuration options are aligned with webpack’s enhanced-resolve.

§Terminology

§Specifier

For CommonJS modules, the specifier is the string passed to the require function. e.g. "id" in require("id").

For ECMAScript modules, the specifier of an import statement is the string after the from keyword, e.g. 'specifier' in import 'specifier' or import { sep } from 'specifier'. Specifiers are also used in export from statements, and as the argument to an import() expression.

This is also named “request” in some places.

§References:

Algorithm adapted from Node.js CommonJS Module Resolution Algorithm and ECMAScript Module Resolution Algorithm.
Tests are ported from enhanced-resolve.
Some code is adapted from parcel-resolver.
The documentation is copied from webpack’s resolve configuration.

§Feature flags

yarn_pnp — Yarn Plug’n’Play

§Example

// See documentation at <https://docs.rs/oxc_resolver>

use std::path::PathBuf;

use oxc_resolver::{
    AliasValue, ResolveOptions, Resolver, TsconfigDiscovery, TsconfigOptions, TsconfigReferences,
};
use pico_args::Arguments;

fn main() {
    let mut args = Arguments::from_env();

    let tsconfig_path = args.value_from_str::<&'static str, PathBuf>("--tsconfig").ok();
    let path = args.free_from_str::<PathBuf>().expect("path");
    let specifier = args.free_from_str::<String>().expect("specifier");

    assert!(path.is_dir(), "{} must be a directory that will be resolved against.", path.display());
    assert!(path.is_absolute(), "{} must be an absolute path.", path.display());

    println!("path: {}", path.to_string_lossy());
    println!("specifier: {specifier}");
    if let Some(path) = &tsconfig_path {
        println!("tsconfig: {}", path.to_string_lossy());
    }

    let options = ResolveOptions {
        alias_fields: vec![vec!["browser".into()]],
        alias: vec![("asdf".into(), vec![AliasValue::from("./test.js")])],
        extensions: vec![".js".into(), ".ts".into()],
        extension_alias: vec![(".js".into(), vec![".ts".into(), ".js".into()])],
        // ESM
        condition_names: vec!["node".into(), "import".into()],
        // CJS
        // condition_names: vec!["node".into(), "require".into()],
        tsconfig: Some(tsconfig_path.map_or_else(
            || TsconfigDiscovery::Auto,
            |config_file| {
                TsconfigDiscovery::Manual(TsconfigOptions {
                    config_file,
                    references: TsconfigReferences::Auto,
                })
            },
        )),
        ..ResolveOptions::default()
    };

    println!();

    match Resolver::new(options).resolve(path, &specifier) {
        Err(error) => println!("Error: {error}"),
        Ok(resolution) => {
            println!("Resolution: {}", resolution.full_path().to_string_lossy());
            println!("Module Type: {:?}", resolution.module_type());
            println!(
                "package.json: {:?}",
                resolution.package_json().map(|p| p.path.to_string_lossy())
            );
        }
    }
}

Structs§

Cache: Cache implementation used for caching filesystem access.
CachedPath
CompilerOptions: Compiler Options
FileMetadata: Metadata information about a file
FileSystemOs
ImportsExportsArray
ImportsExportsEntry
ImportsExportsMap
JSONError: JSON error from serde_json::Error
PackageJson: Serde implementation for the deserialized package.json.
ProjectReference: Project Reference
Resolution: The final path resolution with optional ?query and #fragment
ResolveContext: Context returned from the Resolver::resolve_with_context API
ResolveOptions: Module Resolution Options
ResolverGeneric: Generic implementation of the resolver, can be configured by the Cache trait
TsConfig
TsconfigOptions: Tsconfig Options for ResolveOptions::tsconfig

Enums§

AliasValue: Alias Value for ResolveOptions::alias and ResolveOptions::fallback
EnforceExtension: Value for ResolveOptions::enforce_extension
ExtendsField: Value for the “extends” field.
ImportsExportsKind
ModuleType
PackageType
ResolveError: All resolution errors
Restriction: Value for ResolveOptions::restrictions
SideEffects
SpecifierError: Error for ResolveError::Specifier
TsconfigDiscovery
TsconfigReferences: Configuration for TsconfigOptions::references

Constants§

NODEJS_BUILTINS: Node.js built-in modules

Traits§

FileSystem: File System abstraction used for ResolverGeneric
PathUtil: Extension trait to add path normalization to std’s Path.

Type Aliases§

Alias: Alias for ResolveOptions::alias and ResolveOptions::fallback
CompilerOptionsPathsMap
Resolver: Resolver with the current operating system as the file system