# typescript-transform-paths
> Transforms module resolution paths using TypeScript path mapping and/or custom paths
Latest version **4.0.0** (published 2026-05-17) · MIT license · 0 weekly downloads
## Install
```sh
npm install typescript-transform-paths
pnpm add typescript-transform-paths
yarn add typescript-transform-paths
bun add typescript-transform-paths
```
## Health
**Score 55/100 (C)** — status: active.
Positive: esm support; no vulnerabilities; high maintenance score.
Warnings: low downloads; no types.
## Facts
| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-05-17 |
| First published | 2019-02-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 115.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 496 |
| Maintainers | danielpza |
| Keywords | typescript, transform, transformer, plugin, path, paths, virtual directory, import, require |
## Links
- npm: https://www.npmjs.com/package/typescript-transform-paths
- Repository: https://github.com/LeDDGroup/typescript-transform-paths
- Homepage: https://github.com/LeDDGroup/typescript-transform-paths#readme
- Issues: https://github.com/LeDDGroup/typescript-transform-paths/issues
- npm.io page: https://npm.io/package/typescript-transform-paths
## Dependencies (1)
- [minimatch](https://npm.io/package/minimatch.md) ^10.1.1
## Alternatives
- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads
## Recent versions
- 4.0.0 (latest) — 2026-05-17
- 4.0.0-beta.2 (beta) — 2025-11-06
- 3.5.3-20241222-065611-bce1be7 (test) — 2024-12-22
- 3.4.10-1723087060.2b01c26 (testing) — 2024-08-08
- 3.4.0-alpha (alpha) — 2021-09-18
- 2.1.0-beta2 (beta2) — 2020-11-27
- 2.1.0-beta1 (beta1) — 2020-11-27
- 3.5.6 — 2025-12-31
- 4.0.0-beta — 2025-11-04
- 3.5.5 — 2025-03-15
- 3.5.4 — 2025-03-11
- 3.5.3 — 2024-12-22
- 3.5.3-20241222-064734-2421fd9 — 2024-12-22
- 3.5.3-20241222-063901-1039e07 — 2024-12-22
- 3.5.2 — 2024-11-05
- … 55 more at https://npm.io/package/typescript-transform-paths/versions
## README
typescript-transform-paths
Transform compiled source module resolution paths using TypeScript's paths config, and/or custom resolution paths
[](https://www.npmjs.com/package/typescript-transform-paths)
[](https://actions-badge.atrox.dev/LeDDGroup/typescript-transform-paths/goto?ref=master)
[](https://conventionalcommits.org)
[](https://github.com/prettier/prettier)
> [!TIP]
> Upgrading from v3 to v4? See the [migration](./docs/migrating-to-v4.md) documentation.
> [!IMPORTANT]
> We are [looking for maintainers][issue-439].
> Explore [alternatives][issue-438].
## Setup Steps
### 1. Install
```sh
add -D typescript-transform-paths
```
### 2. Configure
Add it to `plugins` in your `tsconfig.json` file.
#### Example Configuration
```jsonc
{
"compilerOptions": {
"baseUrl": "./",
// Configure your path mapping here
"paths": {
"@utils/*": ["utils/*"],
},
// Note: to transform paths for both the output .js and .d.ts files,
// you need both of the below entries
"plugins": [
// Transform paths in output .js files
{ "transform": "typescript-transform-paths" },
// Transform paths in output .d.ts files (include this line if you output declarations files)
{ "transform": "typescript-transform-paths", "afterDeclarations": true },
],
},
}
```
#### Example Result
`core/index.ts`
```ts
// The following import path is transformed to '../utils/sum'
import { sum } from "@utils/sum";
```
### 3. Use
- Compile with **`tsc`** — Use [ts-patch][ts-patch].
- Run with **`ts-node`** — See the [Wiki][ts-node-wiki].
- Integrate with **Nx** — Add the `typescript-transform-paths/plugins/nx` transformer to the project configuration.
`project.json`
```jsonc
{
/* ... */
"targets": {
"build": {
/* ... */
"options": {
/* ... */
"transformers": [
{
"name": "typescript-transform-paths/plugins/nx",
"options": { "afterDeclarations": true },
},
],
},
},
},
}
```
## Virtual Directories
TypeScript allows defining [Virtual Directories][virtual-directories] via the `rootDirs` compiler option.
To enable Virtual Directory mapping, use the `useRootDirs` plugin option.
`tsconfig.json`
```jsonc
{
"compilerOptions": {
"rootDirs": ["src", "generated"],
"baseUrl": ".",
"paths": {
"#root/*": ["./src/*", "./generated/*"],
},
"plugins": [
{ "transform": "typescript-transform-paths", "useRootDirs": true },
{ "transform": "typescript-transform-paths", "useRootDirs": true, "afterDeclarations": true },
],
},
}
```
#### Example
```text
├src/
├─ subdir/
│ └─ sub-file.ts
├─ file1.ts
├generated/
├─ file2.ts
```
`src/file1.ts`
```ts
import "#root/file2.ts"; // Resolves to './file2'
```
`src/subdir/sub-file.ts`
```ts
import "#root/file2.ts"; // Resolves to '../file2'
import "#root/file1.ts"; // Resolves to '../file1'
```
## Custom Control
### Exclusion Patterns
You can disable transformation for paths based on the resolved file path.
The `exclude` option allows specifying Glob patterns to match against those resolved file paths.
For an example context in which this would be useful, see [issue #83][issue-83].
`tsconfig.json`
```jsonc
{
"compilerOptions": {
"paths": {
"sub-module1/*": ["../../node_modules/sub-module1/*"],
"sub-module2/*": ["../../node_modules/sub-module2/*"],
},
"plugins": [
{
"transform": "typescript-transform-paths",
"exclude": ["**/node_modules/**"],
},
],
},
}
```
```ts
// This path will NOT be transformed
import * as sm1 from "sub-module1/index";
```
### @transform-path
Use the `@transform-path` tag to explicitly specify the output path for a single statement.
```ts
// @transform-path https://cdnjs.cloudflare.com/ajax/libs/react/17.0.1/umd/react.production.min.js
import react from "react"; // Output path will be the URL defined above
```
### @no-transform-path
Use the `@no-transform-path` tag to explicitly disable transformation for a single statement.
```ts
// @no-transform-path
import "normally-transformed"; // This will remain 'normally-transformed' even though
// it has a different value in paths config
```
## Version Compatibility
| typescript-transform-paths | TypeScript | Node.js |
| -------------------------- | --------------------- | ------- |
| ^4.0.0 | >=5.x | >=22 |
| ^3.5.2 | >=3.6.5, >=4.x, >=5.x | >=18 |
## Project Guidelines for Contributors
- Package Manager: `yarn` (`yarn install`)
- Format and lint the code before commit: `prettier` (`yarn format && yarn lint`)
- Commit messages: [Conventional Commit Specs](https://www.conventionalcommits.org/en/v1.0.0/)
- Releases: `changelogen` (`yarn release`)
```shell
GH_TOKEN=$(gh auth token) yarn release
```
## Alternatives
- [Node.js Subpath imports][subpath-imports]
- [Yarn Link Protocol][yarn-link-protocol]
## Maintainers
[ts-patch]: https://github.com/nonara/ts-patch
[ts-node-wiki]: https://github.com/LeDDGroup/typescript-transform-paths/wiki/Integration-with-ts%E2%80%90node
[virtual-directories]: https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs
[issue-83]: https://github.com/LeDDGroup/typescript-transform-paths/issues/83
[issue-438]: https://github.com/LeDDGroup/typescript-transform-paths/issues/438
[issue-439]: https://github.com/LeDDGroup/typescript-transform-paths/issues/439
[subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
[yarn-link-protocol]: https://yarnpkg.com/protocol/link
---
_Source: https://npm.io/package/typescript-transform-paths · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
