Skip to content

Commit d209e75

Browse files
lppeddlppedd
committed
docs: refine the readme and v4 migration content
1 parent 8eb557f commit d209e75

File tree

2 files changed

+82
-78
lines changed

2 files changed

+82
-78
lines changed

‎README.md‎

Lines changed: 62 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,20 @@
1-
> [!IMPORTANT]
2-
> [Looking for maintainers](https://github.com/LeDDGroup/typescript-transform-paths/issues/439)
3-
>
4-
> [Alternatives](https://github.com/LeDDGroup/typescript-transform-paths/issues/438)
5-
6-
---
7-
8-
# typescript-transform-paths
1+
<h1 align="center">typescript-transform-paths</h1>
2+
<p align="center">Transform compiled source module resolution paths using TypeScript's <code>paths</code> config, and/or custom resolution paths</p>
3+
<div align="center">
94

105
[![npm version](https://img.shields.io/npm/v/typescript-transform-paths.svg)](https://www.npmjs.com/package/typescript-transform-paths)
116
[![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)
127
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
13-
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
8+
[![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
149

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

17-
> [!NOTE]
18-
> Upgrading from v3 to v4?, see [migration](./docs/migrating-to-v4.md)
12+
> [!TIP]
13+
> Upgrading from v3 to v4? See the [migration](./docs/migrating-to-v4.md) documentation.
14+
15+
> [!IMPORTANT]
16+
> We are [looking for maintainers][issue-439].
17+
> Explore [alternatives][issue-438].
1918
2019
## Setup Steps
2120

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

2827
### 2. Configure
2928

30-
Add it to _plugins_ in your _tsconfig.json_
29+
Add it to `plugins` in your `tsconfig.json` file.
3130

32-
#### Example Config
31+
#### Example Configuration
3332

3433
```jsonc
3534
{
@@ -39,32 +38,33 @@ Add it to _plugins_ in your _tsconfig.json_
3938
"paths": {
4039
"@utils/*": ["utils/*"],
4140
},
42-
// Note: To transform paths for both the output .js and .d.ts files, you need both of the below entries
41+
// Note: to transform paths for both the output .js and .d.ts files,
42+
// you need both of the below entries
4343
"plugins": [
4444
// Transform paths in output .js files
4545
{ "transform": "typescript-transform-paths" },
4646

47-
// Transform paths in output .d.ts files (Include this line if you output declarations files)
47+
// Transform paths in output .d.ts files (include this line if you output declarations files)
4848
{ "transform": "typescript-transform-paths", "afterDeclarations": true },
4949
],
5050
},
5151
}
5252
```
5353

54-
#### Example result
54+
#### Example Result
5555

5656
`core/index.ts`
5757

58-
```tsx
59-
// The following transforms path to '../utils/sum'
58+
```ts
59+
// The following import path is transformed to '../utils/sum'
6060
import { sum } from "@utils/sum";
6161
```
6262

63-
### 3. Usage
63+
### 3. Use
6464

65-
- **Compile with `tsc`** — Use [ts-patch](https://github.com/nonara/ts-patch)
66-
- **ts-node** — See [wiki](https://github.com/LeDDGroup/typescript-transform-paths/wiki/Integration-with-ts%E2%80%90node)
67-
- **Use with NX** — Add the `typescript-transform-paths/nx-transformer` to project config
65+
- Compile with **`tsc`** — Use [ts-patch][ts-patch].
66+
- Run with **`ts-node`** — See the [Wiki][ts-node-wiki].
67+
- Integrate with **Nx** — Add the `typescript-transform-paths/plugins/nx` transformer to the project configuration.
6868

6969
`project.json`
7070

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

9191
## Virtual Directories
9292

93-
TS allows defining
94-
[virtual directories](https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs)
95-
via the `rootDirs` compiler option.
96-
To enable virtual directory mapping, use the `useRootDirs` plugin option.
93+
TypeScript allows defining [Virtual Directories][virtual-directories] via the `rootDirs` compiler option.
94+
To enable Virtual Directory mapping, use the `useRootDirs` plugin option.
95+
96+
`tsconfig.json`
9797

9898
```jsonc
9999
{
@@ -113,38 +113,38 @@ To enable virtual directory mapping, use the `useRootDirs` plugin option.
113113

114114
#### Example
115115

116-
```
117-
- src/
118-
- subdir/
119-
- sub-file.ts
120-
- file1.ts
121-
- generated/
122-
- file2.ts
116+
```text
117+
├src/
118+
├─ subdir/
119+
│ └─ sub-file.ts
120+
├─ file1.ts
121+
├generated/
122+
├─ file2.ts
123123
```
124124

125125
`src/file1.ts`
126126

127127
```ts
128-
import "#root/file2.ts"; // resolves to './file2'
128+
import "#root/file2.ts"; // Resolves to './file2'
129129
```
130130

131131
`src/subdir/sub-file.ts`
132132

133133
```ts
134-
import "#root/file2.ts"; // resolves to '../file2'
135-
import "#root/file1.ts"; // resolves to '../file1'
134+
import "#root/file2.ts"; // Resolves to '../file2'
135+
import "#root/file1.ts"; // Resolves to '../file1'
136136
```
137137

138138
## Custom Control
139139

140-
### Exclusion patterns
140+
### Exclusion Patterns
141141

142-
You can disable transformation for paths based on the resolved file path. The `exclude` option allows specifying glob
143-
patterns to match against resolved file path.
142+
You can disable transformation for paths based on the resolved file path.
143+
The `exclude` option allows specifying Glob patterns to match against those resolved file paths.
144144

145-
For an example context in which this would be useful, see [Issue #83](https://github.com/LeDDGroup/typescript-transform-paths/issues/83)
145+
For an example context in which this would be useful, see [issue #83][issue-83].
146146

147-
Example:
147+
`tsconfig.json`
148148

149149
```jsonc
150150
{
@@ -164,17 +164,17 @@ Example:
164164
```
165165

166166
```ts
167-
// This path will not be transformed
167+
// This path will NOT be transformed
168168
import * as sm1 from "sub-module1/index";
169169
```
170170

171-
### @transform-path tag
171+
### @transform-path
172172

173173
Use the `@transform-path` tag to explicitly specify the output path for a single statement.
174174

175175
```ts
176176
// @transform-path https://cdnjs.cloudflare.com/ajax/libs/react/17.0.1/umd/react.production.min.js
177-
import react from "react"; // Output path will be the url above
177+
import react from "react"; // Output path will be the URL defined above
178178
```
179179

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

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

189190
## Version Compatibility
190191

191-
| `typescript-transform-paths` | TypeScript | NodeJS |
192-
| ---------------------------- | --------------------- | ------ |
193-
| ^3.5.2 | >=3.6.5, >=4.x, >=5.x | >=18 |
192+
| typescript-transform-paths | TypeScript | Node.js |
193+
|------------------------------|-----------------------|---------|
194+
| ^4.0.0 | >=5.x | >=20 |
195+
| ^3.5.2 | >=3.6.5, >=4.x, >=5.x | >=18 |
194196

195197
## Project Guidelines for Contributors
196198

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

206208
## Alternatives
207209

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

211213
## Maintainers
212214

@@ -218,3 +220,12 @@ GH_TOKEN=$(gh auth token) yarn release
218220
<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>
219221
</tr>
220222
</table>
223+
224+
[ts-patch]: https://github.com/nonara/ts-patch
225+
[ts-node-wiki]: https://github.com/LeDDGroup/typescript-transform-paths/wiki/Integration-with-ts%E2%80%90node
226+
[virtual-directories]: https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs
227+
[issue-83]: https://github.com/LeDDGroup/typescript-transform-paths/issues/83
228+
[issue-438]: https://github.com/LeDDGroup/typescript-transform-paths/issues/438
229+
[issue-439]: https://github.com/LeDDGroup/typescript-transform-paths/issues/439
230+
[subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
231+
[yarn-link-protocol]: https://yarnpkg.com/protocol/link

‎docs/migrating-to-v4.md‎

Lines changed: 20 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,20 @@
1-
# Migrating from v3 to v4
2-
3-
## Breaking Changes
4-
5-
### Package is now ESM only
6-
7-
### Dropped support for older Node.js versions. Requires Node.js >22
8-
9-
### Dropped support for older typescript versions. Requires typescript >5.8.x
10-
11-
### Removed `typescript-transform-paths/register` ts-node entrypoint
12-
13-
See https://typestrong.org/ts-node/docs/compilers/ for how to configure ts-node to use custom transformers.
14-
15-
### Renamed `nx` transformer entrypoint
16-
17-
The nx plugin entrypoint was renamed from `typescript-transform-paths/nx-transformer` to `typescript-transform-paths/plugins/nx`:
18-
19-
```diff
20-
"transformers": [
21-
{
22-
- "name": "typescript-transform-paths/nx-transformer",
23-
+ "name": "typescript-transform-paths/plugins/nx",
24-
"options": { "afterDeclarations": true },
25-
},
26-
],
27-
```
1+
<h1 align="center">Migrating from v3 to v4</h1>
2+
3+
### Breaking Changes
4+
5+
- Package is now **ESM** only.
6+
- Dropped support for old Node.js versions. It now **requires** Node.js `>=22`.
7+
- Dropped support for old TypeScript versions. It now **requires** TypeScript `>=5.x`.
8+
- Removed the `typescript-transform-paths/register` **ts-node** entrypoint.
9+
See https://typestrong.org/ts-node/docs/compilers to understand how to configure **ts-node** to use custom transformers.
10+
- Renamed the **Nx** transformer entrypoint from `typescript-transform-paths/nx-transformer` to `typescript-transform-paths/plugins/nx`.
11+
12+
```diff
13+
"transformers": [
14+
{
15+
- "name": "typescript-transform-paths/nx-transformer",
16+
+ "name": "typescript-transform-paths/plugins/nx",
17+
"options": { "afterDeclarations": true },
18+
},
19+
],
20+
```

0 commit comments

Comments
 (0)