Oxc Resolver

Common errors

• Error: Package subpath '. ' is not defined by "exports" in

  cause Attempting to resolve a package's subpath or main entry point via the `exports` field without matching `conditionNames`.
  fix Configure `ResolveOptions` with `conditionNames: ['node', 'require']` (for CommonJS) or `['node', 'import']` (for ESM) to match the expected resolution conditions for the `exports` field. This tells the resolver which export conditions to consider.

• Error: Module not found: Can't resolve 'your-module'

  cause The module specifier does not resolve to a file or directory based on current options, potentially due to incorrect paths, missing extensions, or unrecognized aliases.
  fix Verify the module path, ensuring all segments are correct. Check `ResolveOptions` for `extensions`, `alias`, `modules`, `mainFields`, and `mainFiles`. If using TypeScript `paths`, ensure you are using `resolveFileSync` or `resolveFileAsync` to trigger `tsconfig.json` discovery.

• Error: Cannot find module 'oxc-resolver' or 'oxc-resolver/index.js' (when using require())

  cause Attempting to `require('oxc-resolver')` in a pure ESM context, or if the package is published as ESM-only.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` extension) and use `import { ... } from 'oxc-resolver';`. If you must use CommonJS, ensure your Node.js version supports ESM interop for CJS, or check if the library provides a CJS entry point.

Warnings

• breaking The behavior of `NODE_PATH` environment variable resolution was implicitly enabled in versions prior to 11.19.0. In `v11.19.0`, a new `node_path` option was introduced to explicitly control this behavior, which can disable it. This might alter resolution if you were relying on implicit `NODE_PATH` handling.
  Fix: If your project relies on `NODE_PATH`, explicitly set the `node_path` option to `true` in `ResolveOptions` to maintain prior behavior, or ensure your module paths are otherwise resolvable.
• gotcha There are distinct differences between `resolver.sync(directory, specifier)` and `resolver.resolveFileSync(file, specifier)`. The `sync` method takes a directory path and relies on manually configured `tsconfig` options. In contrast, `resolveFileSync` takes a file path and automatically discovers the relevant `tsconfig.json` by traversing parent directories, which is crucial for respecting `paths` aliases and project references based on the file's context.
  Fix: For accurate resolution within a TypeScript project, especially for bundlers or linters, prefer `resolver.resolveFileSync` (or `resolveFileAsync`) as it correctly handles `tsconfig.json` discovery and `paths` based on the file's location. Only use `sync` if you intend to resolve strictly from a directory context without automatic `tsconfig` discovery.
• gotcha When resolving packages that utilize the `exports` field in their `package.json`, particularly in CommonJS contexts or when explicit `conditionNames` are not provided, you might encounter 'Package subpath '.' is not defined by "exports"' errors. This occurs because the `exports` field requires specific conditions to match the resolution context (e.g., 'node', 'require', 'import').
  Fix: Ensure that your `ResolveOptions` include appropriate `conditionNames` (e.g., `['node', 'require']` for CommonJS consumers) when resolving modules that define an `exports` field, especially for subpath exports.
• gotcha Yarn Plug'n'Play (PnP) support requires specific conditions to work correctly, including the program being called via a `yarn` command (setting `process.versions.pnp`) and the presence of a `.pnp.cjs` manifest file in a parent directory. Improper setup can lead to module not found errors.
  Fix: Verify that your environment is correctly configured for Yarn PnP when using `oxc-resolver`. Ensure the `yarn_pnp` option is enabled in `ResolveOptions` if you intend to use it, and that the `.pnp.cjs` file is discoverable. Errors related to PnP are often shown as-is rather than generic `NotFound` errors, providing specific debugging cues.

Install

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

Imports

• resolveSync
  wrong:

  const { resolveSync } = require('oxc-resolver')

  correct:

  import { resolveSync } from 'oxc-resolver'

  Primarily designed for ESM usage, though it supports CommonJS module resolution internally. For more complex scenarios, use ResolverFactory.
• ResolverFactory
  wrong:

  const ResolverFactory = require('oxc-resolver').ResolverFactory

  correct:

  import { ResolverFactory } from 'oxc-resolver'

  The ResolverFactory class provides configurable resolution options, including async methods and file-based TSConfig discovery.
• ResolveOptions, ResolveResult

  import type { ResolveOptions, ResolveResult } from 'oxc-resolver'

  TypeScript types for configuration and resolution results.

Quickstart

Demonstrates both basic synchronous module resolution and advanced asynchronous file-based resolution with automatic TypeScript configuration (paths) discovery using `ResolverFactory`.

import { ResolverFactory, resolveSync } from 'oxc-resolver';
import * as path from 'path';
import * as fs from 'fs';

async function runResolutionExample() {
  const tempDir = path.join(process.cwd(), 'temp_oxc_resolver_test');
  
  // Setup: Create a temporary directory structure and tsconfig.json
  fs.mkdirSync(path.join(tempDir, 'src', 'app'), { recursive: true });
  fs.writeFileSync(
    path.join(tempDir, 'tsconfig.json'),
    JSON.stringify({
      compilerOptions: {
        baseUrl: '.',
        paths: {
          '@app/*': ['src/app/*'],
        },
      },
    }, null, 2)
  );
  fs.writeFileSync(path.join(tempDir, 'src', 'app', 'moduleA.ts'), 'export const a = 1;');
  
  // 1. Basic synchronous resolution (directory-based context)
  const simpleResolvedPath = resolveSync(tempDir, './src/app/moduleA.ts');
  console.log('Simple resolved path (sync):', simpleResolvedPath?.path);

  // 2. Advanced resolution using ResolverFactory with file-based context and TSConfig discovery
  const resolver = new ResolverFactory();
  const sourceFilePath = path.join(tempDir, 'src', 'main.ts');
  fs.writeFileSync(sourceFilePath, 'import { a } from "@app/moduleA";'); // Dummy file for context

  const fileBasedResolvedPath = await resolver.resolveFileAsync(sourceFilePath, '@app/moduleA');
  console.log('File-based resolved path (async with tsconfig):', fileBasedResolvedPath?.path);

  // Cleanup
  fs.unlinkSync(path.join(tempDir, 'src', 'app', 'moduleA.ts'));
  fs.unlinkSync(path.join(tempDir, 'tsconfig.json'));
  fs.unlinkSync(sourceFilePath);
  fs.rmdirSync(path.join(tempDir, 'src', 'app'));
  fs.rmdirSync(path.join(tempDir, 'src'));
  fs.rmdirSync(tempDir);
}

runResolutionExample().catch(console.error);