Registry / devops / oxc-resolver

oxc-resolver

JSON →
library11.19.1jsnpmunverified

Oxc Resolver is a high-performance, Rust-ported module resolver designed for Node.js environments, mimicking the behavior of `enhanced-resolve`, `tsconfig-paths-webpack-plugin`, and `tsconfck`. It provides a comprehensive implementation of both ESM and CommonJS module resolution algorithms as specified by Node.js. Currently stable at version 11.19.1, it receives frequent updates with minor version bumps and bug fixes, indicating active development. Key features include built-in support for TypeScript's `tsconfig.json` paths, project references, and automatic `tsconfig` discovery, making it a robust alternative for bundlers, linters, and language servers. It boasts significant performance improvements, such as being 28x faster than `webpack/enhanced-resolve`, and supports an in-memory file system and `tracing` instrumentation, distinguishing it from purely JavaScript-based resolvers.

npm install oxc-resolver
INSTALL
IMPORT
SIG · OXC-RESOLVER
O
oxc-resolver
devopsjavascriptv11.19.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.

resolveSync
import { resolveSync } from 'oxc-resolver'
const { resolveSync } = require('oxc-resolver')
Primarily designed for ESM usage, though it supports CommonJS module resolution internally. For more complex scenarios, use ResolverFactory.
ResolverFactory
import { ResolverFactory } from 'oxc-resolver'
const ResolverFactory = require('oxc-resolver').ResolverFactory
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.

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);
Debug
Known issues
breakingThe 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.
affects: >=11.19.0
gotchaThere 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.
affects: >=11.0.0
gotchaWhen 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.
affects: >=11.0.0
gotchaYarn 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.
affects: >=11.0.0
Errors
Common errors & fixes
Error: Package subpath '. ' is not defined by "exports" in
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'
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())
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.
Upgrade
Version history
11.19.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
oxc-resolver — npm install oxc-resolver · libregistry