UnRS Resolver

Common errors

• Error: Failed to find or read Yarn PnP manifest at /path/to/.pnp.cjs

  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.
  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'

  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.
  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/...

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

Warnings

• gotcha 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.
  Fix: Upgrade `unrs-resolver` to version `1.11.0` or higher to benefit from improved Yarn PnP manifest handling and error reporting.
• gotcha 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.
  Fix: Upgrade `unrs-resolver` to version `1.10.0` or higher, which includes fixes for resolving abnormal relative paths and ensures correct aliasing behavior.
• gotcha 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.
  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).

Install

• npm install unrs-resolver npm
• yarn add unrs-resolver yarn
• pnpm add unrs-resolver pnpm

Imports

• ResolverFactory
  wrong:

  const { ResolverFactory } = require('unrs-resolver');

  correct:

  import { ResolverFactory } from '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.

Quickstart

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}`);
}