LeDDGroup
typescript-transform-paths
Transform compiled source module resolution paths using TypeScript's paths config, and/or custom resolution paths.
Setup Steps
1. Install
<yarn|npm|pnpm> add -D typescript-transform-paths2. Configure
Add it to plugins in your tsconfig.json
Example Config
{
"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
// The following transforms path to '../utils/sum'
import { sum } from "@utils/sum";3. Usage
Compile with
tsc— Use ts-patchUse with ts-node — Add
typescript-transform-paths/registertorequireconfig.tsconfig.json{ "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.tsUse with NX — Add the
typescript-transform-paths/nx-transformerto project configproject.json{ /* ... */ "targets": { "build": { /* ... */ "options": { /* ... */ "transformers": [ { "name": "typescript-transform-paths/nx-transformer", "options": { "afterDeclarations": true }, }, ], }, }, }, }
Virtual Directories
TS allows defining
virtual directories
via the rootDirs compiler option.
To enable virtual directory mapping, use the useRootDirs plugin option.
{
"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.tssrc/file1.ts
import "#root/file2.ts"; // resolves to './file2'src/subdir/sub-file.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
Example:
{
"compilerOptions": {
"paths": {
"sub-module1/*": ["../../node_modules/sub-module1/*"],
"sub-module2/*": ["../../node_modules/sub-module2/*"],
},
"plugins": [
{
"transform": "typescript-transform-paths",
"exclude": ["**/node_modules/**"],
},
],
},
}// 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.
// @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.
// @no-transform-path
import "normally-transformed"; // This will remain 'normally-transformed', even though it has a different value in paths configVersion 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
- Releases:
changelogen(yarn release)
GH_TOKEN=$(gh auth token) yarn releaseAlternatives
Maintainers
 Ron S. |
 Daniel Perez Alvarez |