{"id":13484921,"url":"https://github.com/LeDDGroup/typescript-transform-paths","last_synced_at":"2025-03-27T16:31:32.179Z","repository":{"id":40293853,"uuid":"168888433","full_name":"LeDDGroup/typescript-transform-paths","owner":"LeDDGroup","description":"Transforms module resolution paths using TypeScript path mapping and/or custom paths","archived":false,"fork":false,"pushed_at":"2025-03-24T12:30:32.000Z","size":2085,"stargazers_count":490,"open_issues_count":32,"forks_count":28,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-24T13:33:15.786Z","etag":null,"topics":["absolute","npm-package","path","relative","transform","typescript"],"latest_commit_sha":null,"homepage":"","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/LeDDGroup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["nonara","danielpza"]}},"created_at":"2019-02-02T23:10:52.000Z","updated_at":"2025-03-22T00:02:05.000Z","dependencies_parsed_at":"2024-01-13T19:19:34.492Z","dependency_job_id":"de1d758f-4269-4100-97d0-d515bb84e8ee","html_url":"https://github.com/LeDDGroup/typescript-transform-paths","commit_stats":{"total_commits":351,"total_committers":16,"mean_commits":21.9375,"dds":0.6125356125356125,"last_synced_commit":"7c9816ecad6ab7a214cdcba4b641b01ee4706732"},"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeDDGroup%2Ftypescript-transform-paths","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeDDGroup%2Ftypescript-transform-paths/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeDDGroup%2Ftypescript-transform-paths/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeDDGroup%2Ftypescript-transform-paths/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeDDGroup","download_url":"https://codeload.github.com/LeDDGroup/typescript-transform-paths/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245882438,"owners_count":20687889,"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":["absolute","npm-package","path","relative","transform","typescript"],"created_at":"2024-07-31T17:01:38.892Z","updated_at":"2025-03-27T16:31:32.164Z","avatar_url":"https://github.com/LeDDGroup.png","language":"TypeScript","readme":"# typescript-transform-paths\n\n[![npm version](https://img.shields.io/npm/v/typescript-transform-paths.svg)](https://www.npmjs.com/package/typescript-transform-paths)\n[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2FLeDDGroup%2Ftypescript-transform-paths%2Fbadge%3Fref%3Dmaster\u0026style=flat)](https://actions-badge.atrox.dev/LeDDGroup/typescript-transform-paths/goto?ref=master)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n\nTransform compiled source module resolution paths using TypeScript's `paths` config, and/or custom resolution paths.\n\n## Setup Steps\n\n### 1. Install\n\n```sh\n\u003cyarn|npm|pnpm\u003e add -D typescript-transform-paths\n```\n\n### 2. Configure\n\nAdd it to _plugins_ in your _tsconfig.json_\n\n#### Example Config\n\n```jsonc\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \"./\",\n    // Configure your path mapping here\n    \"paths\": {\n      \"@utils/*\": [\"utils/*\"],\n    },\n    // Note: To transform paths for both the output .js and .d.ts files, you need both of the below entries\n    \"plugins\": [\n      // Transform paths in output .js files\n      { \"transform\": \"typescript-transform-paths\" },\n\n      // Transform paths in output .d.ts files (Include this line if you output declarations files)\n      { \"transform\": \"typescript-transform-paths\", \"afterDeclarations\": true },\n    ],\n  },\n}\n```\n\n#### Example result\n\n`core/index.ts`\n\n```tsx\n// The following transforms path to '../utils/sum'\nimport { sum } from \"@utils/sum\";\n```\n\n### 3. Usage\n\n- **Compile with `tsc`** — Use [ts-patch](https://github.com/nonara/ts-patch)\n\n- **Use with ts-node** — Add `typescript-transform-paths/register` to `require` config.\n\n  `tsconfig.json`\n\n  ```jsonc\n  {\n    \"ts-node\": {\n      \"transpileOnly\": true,\n      \"require\": [ \"typescript-transform-paths/register\" ],\n    },\n    \"compilerOptions\" { /* ... */ }\n  }\n  ```\n\n- **Use with node** — Use the register script: `node -r typescript-transform-paths/register src/index.ts`\n\n- **Use with NX** — Add the `typescript-transform-paths/nx-transformer` to project config\n\n  `project.json`\n\n  ```jsonc\n  {\n    /* ... */\n    \"targets\": {\n      \"build\": {\n        /* ... */\n        \"options\": {\n          /* ... */\n          \"transformers\": [\n            {\n              \"name\": \"typescript-transform-paths/nx-transformer\",\n              \"options\": { \"afterDeclarations\": true },\n            },\n          ],\n        },\n      },\n    },\n  }\n  ```\n\n## Virtual Directories\n\nTS allows defining\n[virtual directories](https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs)\nvia the `rootDirs` compiler option.\nTo enable virtual directory mapping, use the `useRootDirs` plugin option.\n\n```jsonc\n{\n  \"compilerOptions\": {\n    \"rootDirs\": [\"src\", \"generated\"],\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"#root/*\": [\"./src/*\", \"./generated/*\"],\n    },\n    \"plugins\": [\n      { \"transform\": \"typescript-transform-paths\", \"useRootDirs\": true },\n      { \"transform\": \"typescript-transform-paths\", \"useRootDirs\": true, \"afterDeclarations\": true },\n    ],\n  },\n}\n```\n\n#### Example\n\n```\n- src/\n    - subdir/\n      - sub-file.ts\n    - file1.ts\n- generated/\n    - file2.ts\n```\n\n`src/file1.ts`\n\n```ts\nimport \"#root/file2.ts\"; // resolves to './file2'\n```\n\n`src/subdir/sub-file.ts`\n\n```ts\nimport \"#root/file2.ts\"; // resolves to '../file2'\nimport \"#root/file1.ts\"; // resolves to '../file1'\n```\n\n## Custom Control\n\n### Exclusion patterns\n\nYou can disable transformation for paths based on the resolved file path. The `exclude` option allows specifying glob\npatterns to match against resolved file path.\n\nFor an example context in which this would be useful, see [Issue #83](https://github.com/LeDDGroup/typescript-transform-paths/issues/83)\n\nExample:\n\n```jsonc\n{\n  \"compilerOptions\": {\n    \"paths\": {\n      \"sub-module1/*\": [\"../../node_modules/sub-module1/*\"],\n      \"sub-module2/*\": [\"../../node_modules/sub-module2/*\"],\n    },\n    \"plugins\": [\n      {\n        \"transform\": \"typescript-transform-paths\",\n        \"exclude\": [\"**/node_modules/**\"],\n      },\n    ],\n  },\n}\n```\n\n```ts\n// This path will not be transformed\nimport * as sm1 from \"sub-module1/index\";\n```\n\n### @transform-path tag\n\nUse the `@transform-path` tag to explicitly specify the output path for a single statement.\n\n```ts\n// @transform-path https://cdnjs.cloudflare.com/ajax/libs/react/17.0.1/umd/react.production.min.js\nimport react from \"react\"; // Output path will be the url above\n```\n\n### @no-transform-path\n\nUse the `@no-transform-path` tag to explicitly disable transformation for a single statement.\n\n```ts\n// @no-transform-path\nimport \"normally-transformed\"; // This will remain 'normally-transformed', even though it has a different value in paths config\n```\n\n## Version Compatibility\n\n| `typescript-transform-paths` | TypeScript            | NodeJS |\n| ---------------------------- | --------------------- | ------ |\n| ^3.5.2                       | \u003e=3.6.5, \u003e=4.x, \u003e=5.x | \u003e=18   |\n\n## Project Guidelines for Contributors\n\n- Package Manager: `yarn` (`yarn install`)\n- Format and lint the code before commit: `prettier` (`yarn format \u0026\u0026 yarn lint`)\n- Commit messages: [Conventional Commit Specs](https://www.conventionalcommits.org/en/v1.0.0/)\n- Releases: `changelogen` (`yarn release`)\n\n```shell\nGH_TOKEN=$(gh auth token) yarn release\n```\n\n## Alternatives\n\n- [NodeJS subpath imports](https://nodejs.org/api/packages.html#subpath-imports)\n- [Yarn link: protocol](https://yarnpkg.com/protocol/link)\n\n## Maintainers\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/nonara\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/1427565?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRon S.\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/danielpza\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/17787042?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDaniel Perez Alvarez\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n","funding_links":["https://github.com/sponsors/nonara","https://github.com/sponsors/danielpza"],"categories":["TypeScript","目录"],"sub_categories":["TypeScript"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeDDGroup%2Ftypescript-transform-paths","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLeDDGroup%2Ftypescript-transform-paths","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeDDGroup%2Ftypescript-transform-paths/lists"}