{"id":12319,"library":"unrs-resolver","title":"UnRS Resolver","description":"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.","status":"active","version":"1.11.1","language":"javascript","source_language":"en","source_url":"https://github.com/unrs/unrs-resolver","tags":["javascript","typescript"],"install":[{"cmd":"npm install unrs-resolver","lang":"bash","label":"npm"},{"cmd":"yarn add unrs-resolver","lang":"bash","label":"yarn"},{"cmd":"pnpm add unrs-resolver","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for cross-platform binary installation, particularly for legacy npm versions, to ensure native module compilation and compatibility.","package":"napi-postinstall","optional":false}],"imports":[{"note":"Use 'new ResolverFactory()' to create a resolver instance. ESM import is preferred for modern Node.js projects.","wrong":"const { ResolverFactory } = require('unrs-resolver');","symbol":"ResolverFactory","correct":"import { ResolverFactory } from 'unrs-resolver';"},{"note":"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.","symbol":"ResolveOptions","correct":"import type { ResolveOptions } from 'unrs-resolver';"}],"quickstart":{"code":"import { ResolverFactory, ResolveOptions } from 'unrs-resolver';\nimport * as path from 'path';\n\n// Define the root directory for relative paths (e.g., your project root)\nconst projectRoot = process.cwd();\n\n// Create a new resolver instance with custom configurations\nconst resolver = new ResolverFactory({\n  alias: {\n    '@src': path.join(projectRoot, 'src'),\n    '~': projectRoot,\n  },\n  extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],\n  mainFiles: ['index', 'main'],\n  conditionNames: ['node', 'require', 'import'],\n  preferRelative: true,\n  // Example for TypeScript path configuration if tsconfig.json is present\n  typescript: {\n    configFilePath: path.join(projectRoot, 'tsconfig.json'),\n    references: [],\n  },\n} as ResolveOptions); // Cast to ResolveOptions for type safety\n\ntry {\n  // Resolve a Node.js module (e.g., 'lodash')\n  const resolvedLodash = resolver.resolveSync({}, projectRoot, 'lodash');\n  console.log(`Resolved 'lodash': ${resolvedLodash}`);\n\n  // Resolve an aliased path (assuming 'src/utils/my-helper.ts' exists)\n  const resolvedSrcPath = resolver.resolveSync({}, projectRoot, '@src/utils/my-helper');\n  console.log(`Resolved '@src/utils/my-helper': ${resolvedSrcPath}`);\n\n  // Resolve a relative path from a specific base directory\n  const componentsDir = path.join(projectRoot, 'src', 'components');\n  const resolvedRelativePath = resolver.resolveSync({}, componentsDir, './Button');\n  console.log(`Resolved './Button' from ${componentsDir}: ${resolvedRelativePath}`);\n\n} catch (error: any) {\n  console.error(`Module resolution failed: ${error.message}`);\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade `unrs-resolver` to version `1.11.0` or higher to benefit from improved Yarn PnP manifest handling and error reporting.","note":"Version 1.11.0 introduced features to 'return proper errors when failed to find or read yarn pnp manifest' and added 'yarn_pnp' logic to `FileSystem`.","message":"Prior 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.","severity":"gotcha","affected_versions":"<1.11.0"},{"fix":"Upgrade `unrs-resolver` to version `1.10.0` or higher, which includes fixes for resolving abnormal relative paths and ensures correct aliasing behavior.","note":"The README explicitly lists 'absolute path aliasing should not be skipped' as a fixed bug. Version 1.10.0 included support for 'resolving abnormal relative paths with `node_modules`', which is related.","message":"Absolute 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.","severity":"gotcha","affected_versions":"<1.10.0"},{"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).","note":"Platform-specific binding packages like `@unrs/resolver-binding-win32-x64-msvc` are published, indicating reliance on native binaries.","message":"As 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Failed to find or read Yarn PnP manifest at /path/to/.pnp.cjs"},{"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.","cause":"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.","error":"Module resolution failed: Can't resolve '@src/my-module' in '/path/to/project'"},{"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.","cause":"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.","error":"npm ERR! code 1\\nnpm ERR! A complete log of this run can be found in: /path/to/_logs/..."}],"ecosystem":"npm"}