Registry / devops / unrs-resolver

unrs-resolver

JSON →
library1.11.1jsnpmunverified

UnRS Resolver is a high-performance, Rust-ported module resolution library for Node.js environments, currently at version 1.11.1. It provides a robust implementation of both ECMAScript Module (ESM) and CommonJS resolution algorithms, closely aligning with webpack's enhanced-resolve. Key differentiators include built-in `tsconfig-paths-webpack-plugin` support for handling `tsconfig.extends`, `compilerOptions.paths`, and `references`, along with specific enhancements for Yarn Plug'n'Play (PnP) resolution. The library also features an in-memory file system via its `FileSystem` trait and `tracing` instrumentation. It addresses known resolution issues encountered by tools like `eslint-plugin-import-x` and `eslint-import-resolver-typescript`, ensuring greater compatibility and correctness in complex monorepos and build setups. The project maintains an active release cadence, regularly syncing with upstream `oxc-resolver` for improvements and bug fixes.

npm install unrs-resolver
INSTALL
IMPORT
SIG · UNRS-RESOLVER
U
unrs-resolver
devopsjavascriptv1.11.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ResolverFactory
import { ResolverFactory } from 'unrs-resolver';
const { ResolverFactory } = require('unrs-resolver');
Use 'new ResolverFactory()' to create a resolver instance. ESM import is preferred for modern Node.js projects.
ResolveOptions
import type { ResolveOptions } from 'unrs-resolver';
This is a TypeScript type for configuring the resolver options. Use 'import type' for type-only imports to prevent bundling issues and ensure type safety.

Demonstrates synchronous module resolution using a configured `ResolverFactory` instance. It shows how to resolve Node.js modules, custom aliased paths, and relative paths within a project, including basic error handling.

import { ResolverFactory, ResolveOptions } from 'unrs-resolver'; import * as path from 'path'; // Define the root directory for relative paths (e.g., your project root) const projectRoot = process.cwd(); // Create a new resolver instance with custom configurations const resolver = new ResolverFactory({ alias: { '@src': path.join(projectRoot, 'src'), '~': projectRoot, }, extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'], mainFiles: ['index', 'main'], conditionNames: ['node', 'require', 'import'], preferRelative: true, // Example for TypeScript path configuration if tsconfig.json is present typescript: { configFilePath: path.join(projectRoot, 'tsconfig.json'), references: [], }, } as ResolveOptions); // Cast to ResolveOptions for type safety try { // Resolve a Node.js module (e.g., 'lodash') const resolvedLodash = resolver.resolveSync({}, projectRoot, 'lodash'); console.log(`Resolved 'lodash': ${resolvedLodash}`); // Resolve an aliased path (assuming 'src/utils/my-helper.ts' exists) const resolvedSrcPath = resolver.resolveSync({}, projectRoot, '@src/utils/my-helper'); console.log(`Resolved '@src/utils/my-helper': ${resolvedSrcPath}`); // Resolve a relative path from a specific base directory const componentsDir = path.join(projectRoot, 'src', 'components'); const resolvedRelativePath = resolver.resolveSync({}, componentsDir, './Button'); console.log(`Resolved './Button' from ${componentsDir}: ${resolvedRelativePath}`); } catch (error: any) { console.error(`Module resolution failed: ${error.message}`); }
Debug
Known issues
gotchaPrior to `v1.11.0`, `unrs-resolver` could return improper errors or fail to resolve modules correctly when using Yarn PnP, specifically due to issues in finding or reading the PnP manifest.
fix
Upgrade `unrs-resolver` to version `1.11.0` or higher to benefit from improved Yarn PnP manifest handling and error reporting.
affects: <1.11.0
gotchaAbsolute path aliases might not resolve correctly or could be skipped entirely in versions prior to `v1.10.0`, particularly when dealing with abnormal relative paths or complex `tsconfig.compilerOptions.paths` configurations.
fix
Upgrade `unrs-resolver` to version `1.10.0` or higher, which includes fixes for resolving abnormal relative paths and ensures correct aliasing behavior.
affects: <1.10.0
gotchaAs a Rust-based N-API module, `unrs-resolver` requires native compilation during installation. Users on unsupported platforms, with missing C++ build toolchains, or in certain containerized environments may encounter installation failures or runtime errors.
fix
Ensure your system has the necessary C++ build tools installed (e.g., Visual Studio Build Tools on Windows, `build-essential` on Linux, Xcode command-line tools on macOS). Refer to `napi-rs` and `unrs-resolver` documentation for specific platform requirements and known compatibility issues (e.g., on ARM architectures like Raspberry Pi).
affects: >=1.0.0
Errors
Common errors & fixes
Error: Failed to find or read Yarn PnP manifest at /path/to/.pnp.cjs
The resolver could not locate or parse the Yarn PnP manifest file, often due to an incorrect project setup or a bug in older resolver versions.
fix
Ensure Yarn PnP is correctly initialized in your project. If the issue persists, upgrade `unrs-resolver` to `v1.11.0` or newer, which includes fixes for PnP manifest handling.
Module resolution failed: Can't resolve '@src/my-module' in '/path/to/project'
An aliased import path could not be resolved, potentially due to incorrect alias configuration or a bug in `unrs-resolver`'s handling of absolute path aliases.
fix
Double-check the `alias` and `typescript.configFilePath` options in your `ResolverFactory` configuration. If using absolute path aliases, ensure `unrs-resolver` is `v1.10.0` or higher to benefit from relevant bug fixes.
npm ERR! code 1\nnpm ERR! A complete log of this run can be found in: /path/to/_logs/...
This error during `npm install` typically indicates a failure to compile the native Rust module, often due to missing C++ build dependencies on the system where the package is being installed.
fix
Install the required C++ build tools for your operating system (e.g., `sudo apt-get install build-essential` on Debian/Ubuntu, `xcode-select --install` on macOS, Visual Studio Build Tools with C++ desktop development workload on Windows). Consult the `napi-rs` documentation for detailed platform-specific setup instructions.
Upgrade
Version history
1.11.1latest on npm
Audit
Dependencies
napi-postinstallrequiredUsed for cross-platform binary installation, particularly for legacy npm versions, to ensure native module compilation and compatibility.
Agent activity
122 hits · last 30 days
node
112
OpenAI (training)
2
Amazon
1
Resources
unrs-resolver — npm install unrs-resolver · libregistry