\n\n# Oxc Resolver\n\nRust port of [enhanced-resolve], [tsconfig-paths-webpack-plugin] and [tsconfck]\n\n- Released on [crates.io](https://crates.io/crates/oxc_resolver) and [npm](https://npmx.dev/package/oxc-resolver).\n- Implements the [ESM](https://nodejs.org/api/esm.html#resolution-algorithm) and [CommonJS](https://nodejs.org/api/modules.html#all-together) module resolution algorithm specification.\n- Built-in [tsconfig-paths-webpack-plugin]\n - support extending tsconfig defined in `tsconfig.extends`\n - support paths alias defined in `tsconfig.compilerOptions.paths`\n - support project references defined `tsconfig.references`\n - support [template variable ${configDir} for substitution of config files directory path](https://github.com/microsoft/TypeScript/pull/58042)\n- Built-in tsconfig discovery ([tsconfck])\n- Supports in-memory file system via the `FileSystem` trait.\n- Contains `tracing` instrumentation.\n\n## Usage\n\n### npm package\n\nSee index.d.ts for `resolveSync` and `ResolverFactory` API.\n\nQuick example:\n\n```javascript\nimport assert from \"assert\";\nimport path from \"path\";\nimport resolve, { ResolverFactory } from \"./index.js\";\n\n// `resolve`\nassert(resolve.sync(process.cwd(), \"./index.js\").path, path.join(cwd, \"index.js\"));\n\n// `ResolverFactory`\nconst resolver = new ResolverFactory();\nassert(resolver.sync(process.cwd(), \"./index.js\").path, path.join(cwd, \"index.js\"));\n```\n\n#### File-based Resolution\n\nFor file-based resolution with automatic tsconfig discovery, use `resolveFileSync` or `resolveFileAsync`:\n\n```javascript\nconst resolver = new ResolverFactory();\n\n// Resolves from a file path (not directory)\nconst result = resolver.resolveFileSync(\"/path/to/file.ts\", \"./module\");\n\n// Async version\nconst result = await resolver.resolveFileAsync(\"/path/to/file.ts\", \"./module\");\n```\n\n**Key Differences:**\n\n- `sync(directory, specifier)` - Takes a **directory path**, uses manually configured tsconfig if provided\n- `resolveFileSync(file, specifier)` - Takes a **file path**, automatically discovers tsconfig.json by traversing parent directories\n\n**Why use `resolveFileSync`?**\n\nWhen resolving from a specific file (e.g., in bundlers, linters, or language servers), `resolveFileSync` automatically finds the correct `tsconfig.json` by:\n\n- Traversing parent directories from the file location\n- Respecting TypeScript project references\n- Honoring `include`, `exclude`, and `files` fields to determine which tsconfig applies\n- Ensuring tsconfig `paths` aliases work correctly based on the file's context\n\n#### Supports WASM\n\nSee https://stackblitz.com/edit/oxc-resolver for usage example.\n\n### Rust\n\nSee [docs.rs/oxc_resolver](https://docs.rs/oxc_resolver/latest/oxc_resolver).\n\n### [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp)\n\n- For node.js, yarn pnp should work without any configuration, given the following conditions:\n - the program is called with the `yarn` command, where the value [`process.versions.pnp`](https://yarnpkg.com/advanced/pnpapi#processversionspnp) is set.\n - `.pnp.cjs` manifest file exists in the closest directory, searched from the current working directory,\n - no multi-project setup, per second bullet point in [FIND_PNP_MANIFEST](https://yarnpkg.com/advanced/pnp-spec#find_pnp_manifest)\n\n## Terminology\n\n### `directory`\n\nAn **absolute** path to a directory where the specifier is resolved against.\n\nFor CommonJS modules, it is the `__dirname` variable that contains the absolute path to the folder containing current module.\n\nFor ECMAScript modules, it is the value of `import.meta.url`.\n\nBehavior is undefined when given a path to a file.\n\n### `specifier`\n\nThe string passed to `require` or `import`, i.e. `require(\"specifier\")` or `import \"specifier\"`\n\n## Errors and Trouble Shooting\n\n- `Error: Package subpath '.' is not defined by \"exports\" in` - occurs when resolving without `conditionNames`.\n\n## Configuration\n\nThe following usages apply to both Rust and Node.js; the code snippets are written in JavaScript.\n\nTo handle the `exports` field in `package.json`, ESM and CJS need to be differentiated.\n\n### ESM\n\nPer [ESM Resolution algorithm](https://nodejs.org/api/esm.html#resolution-and-loading-algorithm)\n\n> defaultConditions is the conditional environment name array, [\"node\", \"import\"].\n\nThis means when the caller is an ESM import (`import \"module\"`), resolve options should be\n\n```javascript\n{\n \"conditionNames\": [\"node\", \"import\"]\n}\n```\n\n### CJS\n\nPer [CJS Resolution algorithm](https://nodejs.org/api/modules.html#all-together)\n\n> LOAD_PACKAGE_EXPORTS(X, DIR)\n>\n> 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n> `package.json` \"exports\", [\"node\", \"require\"]) defined in the ESM resolver.\n\nThis means when the caller is a CJS require (`require(\"module\")`), resolve options should be\n\n```javascript\n{\n \"conditionNames\": [\"node\", \"require\"]\n}\n```\n\n### Cache\n\nTo support both CJS and ESM with the same cache:\n\n```javascript\nconst esmResolver = new ResolverFactory({\n conditionNames: [\"node\", \"import\"],\n});\n\nconst cjsResolver = esmResolver.cloneWithOptions({\n conditionNames: [\"node\", \"require\"],\n});\n```\n\n### Browser Field\n\nFrom this [non-standard spec](https://github.com/defunctzombie/package-browser-field-spec):\n\n> The `browser` field is provided to JavaScript bundlers or component tools when packaging modules for client side use.\n\nThe option is\n\n```javascript\n{\n \"aliasFields\": [\"browser\"]\n}\n```\n\n### Main Field\n\n```javascript\n{\n \"mainFields\": [\"module\", \"main\"]\n}\n```\n\nQuoting esbuild's documentation:\n\n- `main` - This is [the standard field](https://docs.npmjs.com/files/package.json#main) for all packages that are meant to be used with node. The name main is hard-coded in to node's module resolution logic itself. Because it's intended for use with node, it's reasonable to expect that the file path in this field is a CommonJS-style module.\n- `module` - This field came from a [proposal](https://github.com/dherman/defense-of-dot-js/blob/f31319be735b21739756b87d551f6711bd7aa283/proposal.md) for how to integrate ECMAScript modules into node. Because of this, it's reasonable to expect that the file path in this field is an ECMAScript-style module. This proposal wasn't adopted by node (node uses \"type\": \"module\" instead) but it was adopted by major bundlers because ECMAScript-style modules lead to better tree shaking, or dead code removal.\n- `browser` - This field came from a [proposal](https://gist.github.com/defunctzombie/4339901/49493836fb873ddaa4b8a7aa0ef2352119f69211) that allows bundlers to replace node-specific files or modules with their browser-friendly versions. It lets you specify an alternate browser-specific entry point. Note that it is possible for a package to use both the browser and module field together (see the note below).\n\n## Options\n\nThe following options are aligned with [enhanced-resolve], and is implemented for Rust crate usage.\n\nSee [index.d.ts](https://github.com/oxc-project/oxc-resolver/blob/main/napi/index.d.ts) for Node.js usage.\n\n| Field | Default | Description |\n| ------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| alias | {} | A hash map of module alias configurations |\n| aliasFields | [] | A list of alias fields in description files |\n| extensionAlias | {} | An object which maps extension to extension aliases |\n| conditionNames | [] | A list of exports field condition names |\n| enforceExtension | false | Enforce that an extension from extensions must be used |\n| exportsFields | [\"exports\"] | A list of exports fields in description files |\n| extensions | [\".js\", \".json\", \".node\"] | A list of extensions which should be tried for files |\n| fallback | {} | Same as `alias`, but only used if default resolving fails |\n| fileSystem | | The file system which should be used |\n| fullySpecified | false | Request passed to resolve is already fully specified and extensions or main files are not resolved for it (they are still resolved for internal requests) |\n| mainFields | [\"main\"] | A list of main fields in description files |\n| mainFiles | [\"index\"] | A list of main files in directories |\n| modules | [\"node_modules\"] | A list of directories to resolve modules from, can be absolute path or folder name. Absolute `NODE_PATH` entries are appended automatically when set. |\n| resolveToContext | false | Resolve to a context instead of a file |\n| preferRelative | false | Prefer to resolve module requests as relative request and fallback to resolving as module |\n| preferAbsolute | false | Prefer to resolve server-relative urls as absolute paths before falling back to resolve in roots |\n| restrictions | [] | A list of resolve restrictions |\n| roots | [] | A list of root paths |\n| symlinks | true | Whether to resolve symlinks to their symlinked location |\n| allowPackageExportsInDirectoryResolve | false | Allow `exports` field in `require('../directory')`. Not part of `enhanced-resolve`. |\n\n### TypeScript Configuration\n\n| Field | Default | Description |\n| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| tsconfig | None | TypeScript related config for resolver |\n| tsconfig.configFile | | A relative path to the tsconfig file based on `cwd`, or an absolute path to the tsconfig file. |\n| tsconfig.references | `[]` | - 'auto': inherits from TypeScript config - `string []`: relative path (based on directory of the referencing tsconfig file) or absolute path of referenced project's tsconfig |\n\n### Unimplemented Options\n\n| Field | Default | Description |\n| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| descriptionFiles | [\"package.json\"] | A list of description files to read from |\n| cachePredicate | function() { return true }; | A function which decides whether a request should be cached or not. An object is passed to the function with `path` and `request` properties. |\n| cacheWithContext | true | If unsafe cache is enabled, includes `request.context` in the cache key |\n| plugins | [] | A list of additional resolve plugins which should be applied |\n| resolver | undefined | A prepared Resolver to which the plugins are attached |\n| unsafeCache | false | Use this cache object to unsafely cache the successful requests |\n\n## Debugging\n\nThe following environment variable emits tracing information for the `oxc_resolver::resolve` function.\n\ne.g.\n\n```\n2024-06-11T07:12:20.003537Z DEBUG oxc_resolver: options: ResolveOptions { ... }, path: \"...\", specifier: \"...\", ret: \"...\"\n at /path/to/oxc_resolver-1.8.1/src/lib.rs:212\n in oxc_resolver::resolve with path: \"...\", specifier: \"...\"\n```\n\nThe input values are `options`, `path` and `specifier`, the returned value is `ret`.\n\n### NAPI\n\n```\nOXC_LOG=DEBUG your_program\n```\n\n### Rolldown\n\n```bash\nRD_LOG='oxc_resolver' rolldown build\n```\n\n## Test\n\nTests are ported from\n\n- [enhanced-resolve](https://github.com/webpack/enhanced-resolve/tree/main/test)\n- [tsconfig-path](https://github.com/dividab/tsconfig-paths/blob/master/src/__tests__/data/match-path-data.ts) and [parcel-resolver](https://github.com/parcel-bundler/parcel/tree/v2/packages/utils/node-resolver-core/test/fixture/tsconfig) for tsconfig-paths\n\nTest cases are located in `./src/tests`, fixtures are located in `./tests`\n\n- [x] alias.test.js\n- [x] browserField.test.js\n- [x] dependencies.test.js\n- [x] exportsField.test.js\n- [x] extension-alias.test.js\n- [x] extensions.test.js\n- [x] fallback.test.js\n- [x] fullSpecified.test.js\n- [x] identifier.test.js (see unit test in `crates/oxc_resolver/src/request.rs`)\n- [x] importsField.test.js\n- [x] incorrect-description-file.test.js (need to add ctx.fileDependencies)\n- [x] missing.test.js\n- [x] path.test.js (see unit test in `crates/oxc_resolver/src/path.rs`)\n- [ ] plugins.test.js\n- [ ] pnp.test.js\n- [x] resolve.test.js\n- [x] restrictions.test.js (partially done, regex is not supported yet)\n- [x] roots.test.js\n- [x] scoped-packages.test.js\n- [x] simple.test.js\n- [x] symlink.test.js\n\nIrrelevant tests\n\n- CachedInputFileSystem.test.js\n- SyncAsyncFileSystemDecorator.test.js\n- forEachBail.test.js\n- getPaths.test.js\n- pr-53.test.js\n- unsafe-cache.test.js\n- yield.test.js\n\n## [Sponsored By](https://github.com/sponsors/Boshen)\n\n
![\"Oxc](\"https://oxc.rs/oxc-dark.svg\")
\n ![\"My](\"https://raw.githubusercontent.com/Boshen/sponsors/main/sponsors.svg\")
\n \n