{"id":11512,"library":"oxc-resolver","title":"Oxc Resolver","description":"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.","status":"active","version":"11.19.1","language":"javascript","source_language":"en","source_url":"https://github.com/oxc-project/oxc-resolver","tags":["javascript","typescript"],"install":[{"cmd":"npm install oxc-resolver","lang":"bash","label":"npm"},{"cmd":"yarn add oxc-resolver","lang":"bash","label":"yarn"},{"cmd":"pnpm add oxc-resolver","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily designed for ESM usage, though it supports CommonJS module resolution internally. For more complex scenarios, use ResolverFactory.","wrong":"const { resolveSync } = require('oxc-resolver')","symbol":"resolveSync","correct":"import { resolveSync } from 'oxc-resolver'"},{"note":"The ResolverFactory class provides configurable resolution options, including async methods and file-based TSConfig discovery.","wrong":"const ResolverFactory = require('oxc-resolver').ResolverFactory","symbol":"ResolverFactory","correct":"import { ResolverFactory } from 'oxc-resolver'"},{"note":"TypeScript types for configuration and resolution results.","symbol":"ResolveOptions, ResolveResult","correct":"import type { ResolveOptions, ResolveResult } from 'oxc-resolver'"}],"quickstart":{"code":"import { ResolverFactory, resolveSync } from 'oxc-resolver';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\nasync function runResolutionExample() {\n  const tempDir = path.join(process.cwd(), 'temp_oxc_resolver_test');\n  \n  // Setup: Create a temporary directory structure and tsconfig.json\n  fs.mkdirSync(path.join(tempDir, 'src', 'app'), { recursive: true });\n  fs.writeFileSync(\n    path.join(tempDir, 'tsconfig.json'),\n    JSON.stringify({\n      compilerOptions: {\n        baseUrl: '.',\n        paths: {\n          '@app/*': ['src/app/*'],\n        },\n      },\n    }, null, 2)\n  );\n  fs.writeFileSync(path.join(tempDir, 'src', 'app', 'moduleA.ts'), 'export const a = 1;');\n  \n  // 1. Basic synchronous resolution (directory-based context)\n  const simpleResolvedPath = resolveSync(tempDir, './src/app/moduleA.ts');\n  console.log('Simple resolved path (sync):', simpleResolvedPath?.path);\n\n  // 2. Advanced resolution using ResolverFactory with file-based context and TSConfig discovery\n  const resolver = new ResolverFactory();\n  const sourceFilePath = path.join(tempDir, 'src', 'main.ts');\n  fs.writeFileSync(sourceFilePath, 'import { a } from \"@app/moduleA\";'); // Dummy file for context\n\n  const fileBasedResolvedPath = await resolver.resolveFileAsync(sourceFilePath, '@app/moduleA');\n  console.log('File-based resolved path (async with tsconfig):', fileBasedResolvedPath?.path);\n\n  // Cleanup\n  fs.unlinkSync(path.join(tempDir, 'src', 'app', 'moduleA.ts'));\n  fs.unlinkSync(path.join(tempDir, 'tsconfig.json'));\n  fs.unlinkSync(sourceFilePath);\n  fs.rmdirSync(path.join(tempDir, 'src', 'app'));\n  fs.rmdirSync(path.join(tempDir, 'src'));\n  fs.rmdirSync(tempDir);\n}\n\nrunResolutionExample().catch(console.error);","lang":"typescript","description":"Demonstrates both basic synchronous module resolution and advanced asynchronous file-based resolution with automatic TypeScript configuration (paths) discovery using `ResolverFactory`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=11.19.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=11.0.0"},{"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.","message":"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').","severity":"gotcha","affected_versions":">=11.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=11.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to resolve a package's subpath or main entry point via the `exports` field without matching `conditionNames`.","error":"Error: Package subpath '. ' is not defined by \"exports\" in"},{"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.","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.","error":"Error: Module not found: Can't resolve 'your-module'"},{"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.","cause":"Attempting to `require('oxc-resolver')` in a pure ESM context, or if the package is published as ESM-only.","error":"Error: Cannot find module 'oxc-resolver' or 'oxc-resolver/index.js' (when using require())"}],"ecosystem":"npm"}