{"id":13595761,"url":"https://github.com/dividab/tsconfig-paths","last_synced_at":"2025-04-22T13:15:17.612Z","repository":{"id":38253011,"uuid":"77679670","full_name":"dividab/tsconfig-paths","owner":"dividab","description":"Load node modules according to tsconfig paths, in run-time or via API.","archived":false,"fork":false,"pushed_at":"2025-03-08T09:02:22.000Z","size":474,"stargazers_count":1871,"open_issues_count":107,"forks_count":106,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-22T13:14:47.573Z","etag":null,"topics":["tsconfig","tsconfig-paths","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/dividab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-30T10:31:33.000Z","updated_at":"2025-04-22T06:40:07.000Z","dependencies_parsed_at":"2023-02-08T06:15:33.443Z","dependency_job_id":"5a8233ce-5bb8-49cc-bbce-56c01587a6cd","html_url":"https://github.com/dividab/tsconfig-paths","commit_stats":{"total_commits":347,"total_committers":48,"mean_commits":7.229166666666667,"dds":"0.32564841498559083","last_synced_commit":"5183c7fc5b0c446cf35c5c3ee8c090631faaeddc"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Ftsconfig-paths","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Ftsconfig-paths/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Ftsconfig-paths/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Ftsconfig-paths/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dividab","download_url":"https://codeload.github.com/dividab/tsconfig-paths/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250246727,"owners_count":21398919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["tsconfig","tsconfig-paths","typescript"],"created_at":"2024-08-01T16:01:57.122Z","updated_at":"2025-04-22T13:15:17.582Z","avatar_url":"https://github.com/dividab.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# tsconfig-paths\n\n[![npm version][version-image]][version-url]\n[![build][build-image]][build-url]\n[![Coverage Status][codecov-image]][codecov-url]\n[![MIT license][license-image]][license-url]\n[![code style: prettier][prettier-image]][prettier-url]\n\nUse this to load modules whose location is specified in the `paths` section of `tsconfig.json` or `jsconfig.json`. Both loading at run-time and via API are supported.\n\nTypescript by default mimics the Node.js runtime resolution strategy of modules. But it also allows the use of [path mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html) which allows arbitrary module paths (that doesn't start with \"/\" or \".\") to be specified and mapped to physical paths in the filesystem. The typescript compiler can resolve these paths from `tsconfig` so it will compile OK. But if you then try to execute the compiled files with node (or ts-node), it will only look in the `node_modules` folders all the way up to the root of the filesystem and thus will not find the modules specified by `paths` in `tsconfig`.\n\nIf you require this package's `tsconfig-paths/register` module it will read the `paths` from `tsconfig.json` or `jsconfig.json` and convert node's module loading calls to physical file paths that node can load.\n\n## How to install\n\n```bash\nyarn add --dev tsconfig-paths\n# or\nnpm install --save-dev tsconfig-paths\n# or\nbun install --dev tsconfig-paths\n```\n\n## How to use\n\n### With node\n\n`node -r tsconfig-paths/register main.js`\n\nIf `process.env.TS_NODE_BASEURL` is set it will override the value of `baseUrl` in tsconfig.json:\n\n`TS_NODE_BASEURL=./dist node -r tsconfig-paths/register main.js`\n\n### With ts-node\n\n`ts-node -r tsconfig-paths/register main.ts`\n\nIf `process.env.TS_NODE_PROJECT` is set it will be used to resolved tsconfig.json\n\n### With webpack\n\nFor webpack please use the [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin).\n\n### With mocha and ts-node\n\nAs of Mocha \u003e= 4.0.0 the `--compiler` was [deprecated](https://github.com/mochajs/mocha/wiki/compilers-deprecation). Instead `--require` should be used. You also have to specify a glob that includes `.ts` files because mocha looks after files with `.js` extension by default.\n\n```bash\nmocha -r ts-node/register -r tsconfig-paths/register \"test/**/*.ts\"\n```\n\n### With other commands\n\nAs long as the command has something similar to a `--require` option that can load a module before it starts, tsconfig-paths should be able to work with it.\n\n### With `ts-node` and VSCode\n\nThe following is an example configuration for the `.vscode/launch.json`.\n\n```js\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    {\n      \"name\": \"Debug Functions\",\n      \"request\": \"launch\",\n      \"type\": \"node\",\n      \"runtimeArgs\": [\n        \"-r\",\n        \"${workspaceFolder}/functions/node_modules/ts-node/register\",\n        \"-r\",\n        \"${workspaceFolder}/functions/node_modules/tsconfig-paths/register\"\n      ],\n      \"args\": [\"${workspaceFolder}/functions/src/index.ts\"],\n      \"cwd\": \"${workspaceFolder}\",\n      \"protocol\": \"inspector\",\n      \"env\": {\n        \"NODE_ENV\": \"development\",\n        \"TS_NODE_PROJECT\": \"${workspaceFolder}/functions/tsconfig.json\"\n      },\n      \"outFiles\": [\"${workspaceFolder}/functions/lib/**/*.js\"]\n    }\n  ]\n}\n```\n\n## Bootstrapping with explicit params\n\nIf you want more granular control over tsconfig-paths you can bootstrap it. This can be useful if you for instance have compiled with `tsc` to another directory where `tsconfig.json` doesn't exists.\n\nFor example, create a wrapper script called `tsconfig-paths-bootstrap.js` with the contents below:\n\n```javascript\nconst tsConfig = require(\"./tsconfig.json\");\nconst tsConfigPaths = require(\"tsconfig-paths\");\n\nconst baseUrl = \"./\"; // Either absolute or relative path. If relative it's resolved to current working directory.\nconst cleanup = tsConfigPaths.register({\n  baseUrl,\n  paths: tsConfig.compilerOptions.paths,\n});\n\n// When path registration is no longer needed\ncleanup();\n```\n\nThen run with:\n\n`node -r ./tsconfig-paths-bootstrap.js main.js`\n\n## Configuration Options\n\nYou can set options by passing them before the script path, via programmatic usage or via environment variables.\n\n```bash\nts-node --project customLocation/tsconfig.json -r tsconfig-paths/register \"test/**/*.ts\"\n```\n\n### CLI and Programmatic Options\n\n_Environment variable denoted in parentheses._\n\n- `-P, --project [path]` Path to TypeScript JSON project file (`TS_NODE_PROJECT`)\n\n## Config loading process\n\n1.  Use explicit params passed to register\n2.  Use `process.env.TS_NODE_PROJECT` to resolve tsConfig.json and the specified baseUrl and paths.\n3.  Resolves tsconfig.json from current working directory and the specified baseUrl and paths.\n\n## Programmatic use\n\nThe public API consists of these functions:\n\n- [register](#register)\n- [loadConfig](#loadConfig)\n- [createMatchPath](#createMatchPath) / [createMatchPathAsync](#createMatchPathAsync)\n- [matchFromAbsolutePaths](#matchFromAbsolutePaths) / [matchFromAbsolutePathsAsync](#matchFromAbsolutePathsAsync)\n\n### register\n\n```typescript\nexport interface ExplicitParams {\n  baseUrl: string;\n  paths: { [key: string]: Array\u003cstring\u003e };\n  mainFields?: (string | string[])[];\n  addMatchAll?: boolean;\n  cwd?: string;\n}\n\n/**\n * Installs a custom module load function that can adhere to paths in tsconfig.\n */\nexport function register(explicitParams: ExplicitParams): () =\u003e void;\n```\n\nThis function will patch the node's module loading so it will look for modules in paths specified by `tsconfig.json` or `jsconfig.json`.\nA function is returned for you to reinstate Node's original module loading.\n\n### loadConfig\n\n```typescript\nexport function loadConfig(cwd: string = process.cwd()): ConfigLoaderResult;\n\nexport type ConfigLoaderResult =\n  | ConfigLoaderSuccessResult\n  | ConfigLoaderFailResult;\n\nexport interface ConfigLoaderSuccessResult {\n  resultType: \"success\";\n  absoluteBaseUrl: string;\n  paths: { [key: string]: Array\u003cstring\u003e };\n}\n\nexport interface ConfigLoaderFailResult {\n  resultType: \"failed\";\n  message: string;\n}\n```\n\nThis function loads the `tsconfig.json` or `jsconfig.json`. It will start searching from the specified `cwd` directory. Passing the `tsconfig.json` or `jsconfig.json` file directly instead of a directory also works.\n\n### createMatchPath\n\n```typescript\n/**\n * Function that can match a path\n */\nexport interface MatchPath {\n  (\n    requestedModule: string,\n    readJson?: Filesystem.ReadJsonSync,\n    fileExists?: (name: string) =\u003e boolean,\n    extensions?: ReadonlyArray\u003cstring\u003e\n  ): string | undefined;\n}\n\n/**\n * Creates a function that can resolve paths according to tsconfig paths property.\n * @param absoluteBaseUrl Absolute version of baseUrl as specified in tsconfig.\n * @param paths The paths as specified in tsconfig.\n * @param mainFields A list of package.json field names to try when resolving module files. Select a nested field using an array of field names.\n * @param addMatchAll Add a match-all \"*\" rule if none is present\n * @returns a function that can resolve paths.\n */\nexport function createMatchPath(\n  absoluteBaseUrl: string,\n  paths: { [key: string]: Array\u003cstring\u003e },\n  mainFields: (string | string[])[] = [\"main\"],\n  addMatchAll: boolean = true\n): MatchPath {\n```\n\nThe `createMatchPath` function will create a function that can match paths. It accepts `baseUrl` and `paths` directly as they are specified in tsconfig and will handle resolving paths to absolute form. The created function has the signature specified by the type `MatchPath` above.\n\n### matchFromAbsolutePaths\n\n```typescript\n/**\n * Finds a path from tsconfig that matches a module load request.\n * @param absolutePathMappings The paths to try as specified in tsconfig but resolved to absolute form.\n * @param requestedModule The required module name.\n * @param readJson Function that can read json from a path (useful for testing).\n * @param fileExists Function that checks for existence of a file at a path (useful for testing).\n * @param extensions File extensions to probe for (useful for testing).\n * @param mainFields A list of package.json field names to try when resolving module files. Select a nested field using an array of field names.\n * @returns the found path, or undefined if no path was found.\n */\nexport function matchFromAbsolutePaths(\n  absolutePathMappings: ReadonlyArray\u003cMappingEntry.MappingEntry\u003e,\n  requestedModule: string,\n  readJson: Filesystem.ReadJsonSync = Filesystem.readJsonFromDiskSync,\n  fileExists: Filesystem.FileExistsSync = Filesystem.fileExistsSync,\n  extensions: Array\u003cstring\u003e = Object.keys(require.extensions),\n  mainFields: (string | string[])[] = [\"main\"]\n): string | undefined {\n```\n\nThis function is lower level and requires that the paths as already been resolved to absolute form and sorted in correct order into an array.\n\n### createMatchPathAsync\n\nThis is the async version of `createMatchPath`. It has the same signature but with a callback parameter for the result.\n\n### matchFromAbsolutePathsAsync\n\nThis is the async version of `matchFromAbsolutePaths`. It has the same signature but with a callback parameter for the result.\n\n## How to publish\n\n```\nyarn version --patch\nyarn version --minor\nyarn version --major\n```\n\n[version-image]: https://img.shields.io/npm/v/tsconfig-paths.svg?style=flat\n[version-url]: https://www.npmjs.com/package/tsconfig-paths\n[build-image]: https://github.com/dividab/tsconfig-paths/workflows/CI/badge.svg\n[build-url]: https://github.com/dividab/tsconfig-paths/actions/workflows/ci.yml?query=branch%3Amaster\n[codecov-image]: https://codecov.io/gh/dividab/tsconfig-paths/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/dividab/tsconfig-paths\n[license-image]: https://img.shields.io/github/license/dividab/tsconfig-paths.svg?style=flat\n[license-url]: https://opensource.org/licenses/MIT\n[prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg\n[prettier-url]: https://github.com/prettier/prettier\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdividab%2Ftsconfig-paths","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdividab%2Ftsconfig-paths","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdividab%2Ftsconfig-paths/lists"}