Skip to content

docs: refine the readme and v4 migration content #455

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 6, 2025
Merged

docs: refine the readme and v4 migration content #455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 62 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,20 @@
> [!IMPORTANT]
> [Looking for maintainers](https://github.com/LeDDGroup/typescript-transform-paths/issues/439)
>
> [Alternatives](https://github.com/LeDDGroup/typescript-transform-paths/issues/438)

---

# typescript-transform-paths
<h1 align="center">typescript-transform-paths</h1>
<p align="center">Transform compiled source module resolution paths using TypeScript's <code>paths</code> config, and/or custom resolution paths</p>
<div align="center">

[![npm version](https://img.shields.io/npm/v/typescript-transform-paths.svg)](https://www.npmjs.com/package/typescript-transform-paths)
[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2FLeDDGroup%2Ftypescript-transform-paths%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/LeDDGroup/typescript-transform-paths/goto?ref=master)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

Transform compiled source module resolution paths using TypeScript's `paths` config, and/or custom resolution paths.
</div>

> [!NOTE]
> Upgrading from v3 to v4?, see [migration](./docs/migrating-to-v4.md)
> [!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

Expand All @@ -27,9 +26,9 @@ Transform compiled source module resolution paths using TypeScript's `paths` con

### 2. Configure

Add it to _plugins_ in your _tsconfig.json_
Add it to `plugins` in your `tsconfig.json` file.

#### Example Config
#### Example Configuration

```jsonc
{
Expand All @@ -39,32 +38,33 @@ Add it to _plugins_ in your _tsconfig.json_
"paths": {
"@utils/*": ["utils/*"],
},
// Note: To transform paths for both the output .js and .d.ts files, you need both of the below entries
// 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 paths in output .d.ts files (include this line if you output declarations files)
{ "transform": "typescript-transform-paths", "afterDeclarations": true },
],
},
}
```

#### Example result
#### Example Result

`core/index.ts`

```tsx
// The following transforms path to '../utils/sum'
```ts
// The following import path is transformed to '../utils/sum'
import { sum } from "@utils/sum";
```

### 3. Usage
### 3. Use

- **Compile with `tsc`** — Use [ts-patch](https://github.com/nonara/ts-patch)
- **ts-node** — See [wiki](https://github.com/LeDDGroup/typescript-transform-paths/wiki/Integration-with-ts%E2%80%90node)
- **Use with NX** — Add the `typescript-transform-paths/nx-transformer` to project config
- 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`

Expand All @@ -90,10 +90,10 @@ import { sum } from "@utils/sum";

## Virtual Directories

TS allows defining
[virtual directories](https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs)
via the `rootDirs` compiler option.
To enable virtual directory mapping, use the `useRootDirs` plugin option.
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
{
Expand All @@ -113,38 +113,38 @@ To enable virtual directory mapping, use the `useRootDirs` plugin option.

#### Example

```
- src/
- subdir/
- sub-file.ts
- file1.ts
- generated/
- file2.ts
```text
├src/
├─ subdir/
│ └─ sub-file.ts
├─ file1.ts
├generated/
├─ file2.ts
```

`src/file1.ts`

```ts
import "#root/file2.ts"; // resolves to './file2'
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'
import "#root/file2.ts"; // Resolves to '../file2'
import "#root/file1.ts"; // Resolves to '../file1'
```

## Custom Control

### Exclusion patterns
### Exclusion Patterns

You can disable transformation for paths based on the resolved file path. The `exclude` option allows specifying glob
patterns to match against resolved file path.
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](https://github.com/LeDDGroup/typescript-transform-paths/issues/83)
For an example context in which this would be useful, see [issue #83][issue-83].

Example:
`tsconfig.json`

```jsonc
{
Expand All @@ -164,17 +164,17 @@ Example:
```

```ts
// This path will not be transformed
// This path will NOT be transformed
import * as sm1 from "sub-module1/index";
```

### @transform-path tag
### @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 above
import react from "react"; // Output path will be the URL defined above
```

### @no-transform-path
Expand All @@ -183,14 +183,16 @@ Use the `@no-transform-path` tag to explicitly disable transformation for a sing

```ts
// @no-transform-path
import "normally-transformed"; // This will remain 'normally-transformed', even though it has a different value in paths config
import "normally-transformed"; // This will remain 'normally-transformed' even though
// it has a different value in paths config
```

## Version Compatibility

| `typescript-transform-paths` | TypeScript | NodeJS |
| ---------------------------- | --------------------- | ------ |
| ^3.5.2 | >=3.6.5, >=4.x, >=5.x | >=18 |
| 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

Expand All @@ -205,8 +207,8 @@ GH_TOKEN=$(gh auth token) yarn release

## Alternatives

- [NodeJS subpath imports](https://nodejs.org/api/packages.html#subpath-imports)
- [Yarn link: protocol](https://yarnpkg.com/protocol/link)
- [Node.js Subpath imports][subpath-imports]
- [Yarn Link Protocol][yarn-link-protocol]

## Maintainers

Expand All @@ -218,3 +220,12 @@ GH_TOKEN=$(gh auth token) yarn release
<td align="center"><a href="https://github.com/danielpza"><img src="https://avatars2.githubusercontent.com/u/17787042?v=4" width="100px;" alt=""/><br /><sub><b>Daniel Perez</b></sub></a></td>
</tr>
</table>

[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
47 changes: 20 additions & 27 deletions docs/migrating-to-v4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,20 @@
# Migrating from v3 to v4

## Breaking Changes

### Package is now ESM only

### Dropped support for older Node.js versions. Requires Node.js >22

### Dropped support for older typescript versions. Requires typescript >5.8.x

### Removed `typescript-transform-paths/register` ts-node entrypoint

See https://typestrong.org/ts-node/docs/compilers/ for how to configure ts-node to use custom transformers.

### Renamed `nx` transformer entrypoint

The nx plugin entrypoint was renamed from `typescript-transform-paths/nx-transformer` to `typescript-transform-paths/plugins/nx`:

```diff
"transformers": [
{
- "name": "typescript-transform-paths/nx-transformer",
+ "name": "typescript-transform-paths/plugins/nx",
"options": { "afterDeclarations": true },
},
],
```
<h1 align="center">Migrating from v3 to v4</h1>

### Breaking Changes

- Package is now **ESM** only.
- Dropped support for old Node.js versions. It now **requires** Node.js `>=22`.
- Dropped support for old TypeScript versions. It now **requires** TypeScript `>=5.x`.
- Removed the `typescript-transform-paths/register` **ts-node** entrypoint.
See https://typestrong.org/ts-node/docs/compilers to understand how to configure **ts-node** to use custom transformers.
- Renamed the **Nx** transformer entrypoint from `typescript-transform-paths/nx-transformer` to `typescript-transform-paths/plugins/nx`.

```diff
"transformers": [
{
- "name": "typescript-transform-paths/nx-transformer",
+ "name": "typescript-transform-paths/plugins/nx",
"options": { "afterDeclarations": true },
},
],
```