{"id":35542587,"url":"https://github.com/rstackjs/rspack-resolver","last_synced_at":"2026-01-13T23:38:39.866Z","repository":{"id":247177594,"uuid":"825211961","full_name":"rstackjs/rspack-resolver","owner":"rstackjs","description":"Rust Port of enhanced-resolve","archived":false,"fork":false,"pushed_at":"2026-01-11T17:35:23.000Z","size":4525,"stargazers_count":40,"open_issues_count":10,"forks_count":6,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-01-11T20:25:18.062Z","etag":null,"topics":["resolver","rspack"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rstackjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-07T06:08:37.000Z","updated_at":"2026-01-04T03:42:55.000Z","dependencies_parsed_at":"2025-12-30T17:07:59.240Z","dependency_job_id":null,"html_url":"https://github.com/rstackjs/rspack-resolver","commit_stats":null,"previous_names":["web-infra-dev/rspack-resolver"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/rstackjs/rspack-resolver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frspack-resolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frspack-resolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frspack-resolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frspack-resolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstackjs","download_url":"https://codeload.github.com/rstackjs/rspack-resolver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frspack-resolver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["resolver","rspack"],"created_at":"2026-01-04T05:13:30.235Z","updated_at":"2026-01-13T23:38:39.860Z","avatar_url":"https://github.com/rstackjs.png","language":"Rust","readme":"# Rspack Resolver\n\nRust port of [enhanced-resolve](https://github.com/webpack/enhanced-resolve).\n\n- built-in [tsconfig-paths-webpack-plugin](https://github.com/jonaskello/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- supports in-memory file system via the `FileSystem` trait\n- supports Yarn's [Plug'n'Play](https://yarnpkg.com/features/pnp)\n- contains `tracing` instrumentation\n\n## Usage\n\n### Basic npm Usage\n\nUse the opinionated **synchronous** resolver with default options:\n\n```js\nimport * as resolver from \"@rspack/resolver\";\n\n// Use the opinionated sync resolver with default options\nconst { path: resolvedPath } = resolver.sync(contextPath, \"./index.js\");\n\n// When resolution fails\nconst result = resolver.sync(contextPath, \"./noExist.js\");\n// result =\u003e { error: \"Cannot find module './noExist.js'\" }\n```\n\nThere's also an equivalent async API:\n\n```js\nimport * as resolver from \"@rspack/resolver\";\n\n// Use the opinionated sync resolver with default options\nconst { path: resolvedPath } = await resolver.async(contextPath, \"./index.js\");\n```\n\n### Custom Resolver with Options\n\nYou can customize the resolver using `ResolverFactory`:\n\n```javascript\nimport { ResolverFactory } from \"@rspack/resolver\";\n\nconst resolver = new ResolverFactory(resolveOptions);\n\n// Sync API\nconst result = resolver.sync(contextPath, \"./request.js\");\n// result =\u003e { path: \"/the/resolved/path/index.js\" }\n//        or { error: \"Cannot find module './request.js'\" }\n\n// Async API\nconst result = await resolver.async(contextPath, \"./request.js\");\n// result =\u003e { path: \"/the/resolved/path/index.js\" }\n//        or { error: \"Cannot find module './request.js'\" }\n```\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\u003e 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\u003e LOAD_PACKAGE_EXPORTS(X, DIR)\n\u003e\n\u003e 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n\u003e    `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\u003e 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## Errors \u0026 Trouble Shooting\n\n- `Error: Package subpath '.' is not defined by \"exports\" in` - occurs when resolving without `conditionNames`.\n\n## Options\n\nThe options are aligned with [enhanced-resolve](https://github.com/webpack/enhanced-resolve).\n\n| Field            | Default                   | Description                                                                                                                                               |\n| ---------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| alias            | []                        | A list of module alias configurations or an object which maps key to value                                                                                |\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| descriptionFiles | [\"package.json\"]          | A list of description files to read from                                                                                                                  |\n| enforceExtension | false                     | Enforce that a 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                                                                        |\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\n### Other Options\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 of tsconfig file.                                                                                                                                                                                                                                                                                                                 |\n| tsconfig.references | `[]`    | - 'auto': inherits from TypeScript config \u003cbr/\u003e - `string []`: relative path (based on directory of the referencing tsconfig file) or absolute path of referenced project's tsconfig                                                                                                                                                                                                                       |\n| enablePnp           | false   | Enable Yarn Plug'n'Play support                                                                                                                                                                                                                                                                                                                                                                            |\n| pnpManifest         | None    | Absolute path to the Yarn Plug'n'Play manifest file; takes effect when PnP is enabled. \u003cbr/\u003e - `None`: PnP manifest located in the nearest ancestor directory from every resolving's path; \u003cbr/\u003e - `Some(PathBuf)`: Use a specific PnP manifest file. This is useful when enabling PnP with `enableGlobalCache: true`, but users must ensure there are no cross-project requires across Yarn PnP projects. |\n\nIn the context of `@rspack/resolver`, the `tsconfig.references` option helps isolate the `paths` configurations of different TypeScript projects.\nThis ensures that path aliases defined in one TypeScript project do not unintentionally affect the resolving behavior of another.\n\nGiven the following [project](https://github.com/rstackjs/rspack-resolver/blob/main/examples/tsconfig_references) structure:\n\n```txt\n├── app\n│   ├── mock_foo\n│   │   ├── index.js\n│   │   └── package.json\n│   ├── package.json\n│   ├── src\n│   │   └── index.ts\n│   ├── tsconfig.json\n│   └── webpack.config.js\n└── component\n    ├── index.js\n    ├── mock_foo\n    │   ├── index.js\n    │   └── package.json\n    ├── package.json\n    ├── src\n    │   └── index.ts\n    └── tsconfig.json\n```\n\n- Both `app` and `component` have their own tsconfig.json.\n- Each defines a path alias `foo` pointing to their respective `mock_foo` directory.\n- `app/tsconfig.json` includes `component` as a referenced project.\n\nWhen configuring `@rspack/resolver` with `app/tsconfig.json`,\nthe resolving result for `import foo` in `component/src/index.ts` differs based on whether `tsconfig.references` is enabled:\n\n| `tsconfig.references` | Resolve Result                | Behavior                                                                                                                                                              |\n| --------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Disabled              | `app/mock_foo/index.js`       | Uses the root `tsconfig.json`’s path alias for all modules; \u003cbr/\u003eSame as [tsconfig-paths-webpack-plugin](https://www.npmjs.com/package/tsconfig-paths-webpack-plugin) |\n| Enabled               | `component/mock_foo/index.js` | Using the referenced project's own `paths` config                                                                                                                     |\n\n### Unimplemented Options\n\n| Field            | Default                     | Description                                                                                                                                   |\n| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\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\u003e [!NOTE]  \n\u003e **Rspack-resolver** is a fork of [oxc-resolver](https://github.com/oxc-project/oxc-resolver?utm_source=chatgpt.com), maintained specifically for use in [Rspack](https://github.com/web-infra-dev/rspack?utm_source=chatgpt.com).\n\u003e\n\u003e While it originated from `oxc-resolver`,\n\u003e we decided to maintain a fork because Rspack requires a different [file system API](https://github.com/rstackjs/rspack-resolver/pull/38).\n\u003e This ensures better alignment with Rspack’s design and long-term stability, while still benefiting from the foundation laid by `oxc-resolver`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstackjs%2Frspack-resolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstackjs%2Frspack-resolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstackjs%2Frspack-resolver/lists"}