Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/LeDDGroup/typescript-transform-paths
Transforms module resolution paths using TypeScript path mapping and/or custom paths
https://github.com/LeDDGroup/typescript-transform-paths
absolute npm-package path relative transform typescript
Last synced: about 1 month ago
JSON representation
Transforms module resolution paths using TypeScript path mapping and/or custom paths
- Host: GitHub
- URL: https://github.com/LeDDGroup/typescript-transform-paths
- Owner: LeDDGroup
- License: mit
- Created: 2019-02-02T23:10:52.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T19:58:48.000Z (about 2 months ago)
- Last Synced: 2024-10-23T12:33:13.933Z (about 2 months ago)
- Topics: absolute, npm-package, path, relative, transform, typescript
- Language: TypeScript
- Homepage:
- Size: 1.99 MB
- Stars: 481
- Watchers: 6
- Forks: 26
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-github-star - typescript-transform-paths
README
# 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
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";
```
### @transform-path tag
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
```
### @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
```
## 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
