typescript-transform-paths
Version:
Transforms module resolution paths using TypeScript path mapping and/or custom paths
227 lines (173 loc) • 6.21 kB
Markdown
# typescript-transform-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)
Transform compiled source module resolution paths using TypeScript's `paths` config, and/or custom resolution paths.
## Setup Steps
### 1. Install
```sh
<yarn|npm|pnpm> add -D typescript-transform-paths
```
### 2. Configure
Add it to _plugins_ in your _tsconfig.json_
#### Example Config
```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`
```tsx
// The following transforms path to '../utils/sum'
import { sum } from "@utils/sum";
```
### 3. Usage
- **Compile with `tsc`** — Use [ts-patch](https://github.com/nonara/ts-patch)
- **Use with ts-node** — Add `typescript-transform-paths/register` to `require` config.
`tsconfig.json`
```jsonc
{
"ts-node": {
"transpileOnly": true,
"require": [ "typescript-transform-paths/register" ],
},
"compilerOptions" { /* ... */ }
}
```
- **Use with node** — Use the register script: `node -r typescript-transform-paths/register src/index.ts`
- **Use with NX** — Add the `typescript-transform-paths/nx-transformer` to project config
`project.json`
```jsonc
{
/* ... */
"targets": {
"build": {
/* ... */
"options": {
/* ... */
"transformers": [
{
"name": "typescript-transform-paths/nx-transformer",
"options": { "afterDeclarations": true },
},
],
},
},
},
}
```
## 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.
```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
```
- 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 resolved file path.
For an example context in which this would be useful, see [Issue #83](https://github.com/LeDDGroup/typescript-transform-paths/issues/83)
Example:
```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";
```
### -path tag
Use the `-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
```
### -transform-path
Use the `-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 | NodeJS |
| ---------------------------- | --------------------- | ------ |
| ^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
- [NodeJS subpath imports](https://nodejs.org/api/packages.html#subpath-imports)
- [Yarn link: protocol](https://yarnpkg.com/protocol/link)
## Maintainers
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<td align="center"><a href="https://github.com/nonara"><img src="https://avatars0.githubusercontent.com/u/1427565?v=4" width="100px;" alt=""/><br /><sub><b>Ron S.</b></sub></a></td>
<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 Alvarez</b></sub></a></td>
</tr>
</table>