Skip to content

Commit bdfaf7a

Browse files
committed
docs: Update readme
1 parent 011871e commit bdfaf7a

File tree

1 file changed

+29
-49
lines changed

1 file changed

+29
-49
lines changed

README.md

Lines changed: 29 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,21 @@
66
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
77
![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)
88

9-
Transform module resolution paths in compiled output source to conform with `TypeScript` internal resolution via `tsconfig.json` settings (`paths`, `rootDirs`, `baseUrl`)
9+
Transform compiled source module resolution paths using TypeScript's `paths` config, and/or custom resolution paths.
1010

11-
## Install
11+
## Setup Steps
12+
13+
### 1. Install
1214

1315
```sh
1416
<yarn|npm|pnpm> add -D typescript-transform-paths
1517
```
1618

17-
## Usage with [ts-patch](https://github.com/nonara/ts-patch) or [ttypescript](https://github.com/cevek/ttypescript/)
19+
### 2. Configure
1820

1921
Add it to _plugins_ in your _tsconfig.json_
2022

21-
### Example Config
23+
#### Example Config
2224

2325
```jsonc
2426
{
@@ -28,7 +30,7 @@ Add it to _plugins_ in your _tsconfig.json_
2830
"paths": {
2931
"@utils/*": ["utils/*"]
3032
},
31-
// Note: To transform paths in both .js and .d.ts files, be sure to add both lines to plugins
33+
// Note: To transform paths for both the output .js and .d.ts files, you need both of the below entries
3234
"plugins": [
3335
// Transform paths in output .js files
3436
{ "transform": "typescript-transform-paths" },
@@ -39,18 +41,32 @@ Add it to _plugins_ in your _tsconfig.json_
3941
}
4042
}
4143
```
42-
`core/index.ts`
44+
#### Example result
45+
4346
```tsx
47+
// The following transforms path to '../utils/sum'
4448
import { sum } from "@utils/sum";
45-
sum(2, 3);
4649
```
4750

48-
`core/index.js` (compiled output)
49-
```js
50-
// core/index.js
51-
var sum_1 = require("../utils/sum");
52-
sum_1.sum(2, 3);
53-
```
51+
### 3. Usage
52+
53+
- **To compile with `tsc`** — Use [ts-patch](https://github.com/nonara/ts-patch)
54+
55+
56+
- **To use with ts-node** — Add `typescript-trasnsform-paths/register` to `require` config.
57+
58+
`tsconfig.json`
59+
```jsonc
60+
{
61+
"ts-node": {
62+
"transpileOnly": true,
63+
"require": [ "typescript-transform-paths/register" ],
64+
},
65+
"compilerOptions" { /* ... */ }
66+
}
67+
```
68+
69+
- **To use with node** — Use the register script: `node -r typescript-transform-paths/register src/index.ts`
5470

5571
## Virtual Directories
5672
TS allows defining
@@ -145,42 +161,6 @@ Use the `@no-transform-path` tag to explicitly disable transformation for a sing
145161
import 'normally-transformed' // This will remain 'normally-transformed', even though it has a different value in paths config
146162
```
147163
148-
## `ts-node` & TS Compiler API Usage
149-
150-
### Note
151-
Most people using `ts-node` can achieve what they want without the transformer, by using [tsconfig-paths](https://github.com/dividab/tsconfig-paths#readme]) (ie. `ts-node -r tsconfig-paths`)
152-
153-
### Others
154-
155-
If you'd still like to use the transformer, it is now possible to do so programmatically, with or without a `Program` instance. This can be done via `ts-node` or the compiler API using `ts.transform()`.
156-
157-
Here is an example of how to register `ts-node` with the transformer:
158-
159-
```ts
160-
import transformer, { TsTransformPathsConfig } from 'typescript-transform-paths';
161-
import { register } from 'ts-node';
162-
import ts from 'typescript';
163-
164-
const pluginConfig: TsTransformPathsConfig = {
165-
useRootDirs: false
166-
};
167-
168-
// Use this code if using transpileOnly
169-
register({
170-
transpileOnly: true,
171-
transformers: {
172-
before: [ transformer(/* Program */ undefined, pluginConfig) ]
173-
}
174-
});
175-
176-
// Use this if not using transpileOnly
177-
register({
178-
transformers: (program: ts.Program) => { before: [ transformer(program, pluginConfig) ] }
179-
});
180-
```
181-
182-
For TS compiler API usage example, have a look at the logic in [specific.test.ts](https://github.com/LeDDGroup/typescript-transform-paths/blob/master/test/tests/transformer/specific.test.ts) for `manual` mode.
183-
184164
## Articles
185165
186166
- [Node Consumable Modules With Typescript Paths](https://medium.com/@ole.ersoy/node-consumable-modules-with-typescript-paths-ed88a5f332fa?postPublishedType=initial) by [oleersoy](https://github.com/oleersoy)

0 commit comments

Comments
 (0)