Registry /
devops / typescript-transform-paths
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
transformer
✓ { "transform": "typescript-transform-paths" }
✗ import * as transform from 'typescript-transform-paths'
This package is a TypeScript compiler plugin, configured directly in `tsconfig.json`'s `plugins` array. It is not imported as a runtime module for direct use in application code, but rather invoked by the TypeScript compiler pipeline or build tools like `ts-patch`.
afterDeclarations transformer
✓ { "transform": "typescript-transform-paths", "afterDeclarations": true }
✗ { "transform": "typescript-transform-paths/afterDeclarations" }
To transform paths in `.d.ts` files, a separate plugin entry with `"afterDeclarations": true` is required in `tsconfig.json`. This is critical for ensuring type declarations correctly reflect the transformed module paths, especially when publishing libraries.
register
✓ node -r typescript-transform-paths/register your-app.js
✗ require('typescript-transform-paths/register')
For runtime resolution with `node` or `ts-node`, use the provided register hook. In `ts-node` configuration, add `"typescript-transform-paths/register"` to the `require` array. This is a side-effect import that modifies module resolution globally.
nx-transformer
✓ { "name": "typescript-transform-paths/nx-transformer" }
When integrating with NX, specify the transformer name directly in the project's `project.json` build targets. This transformer is specifically designed for the NX build pipeline and allows for `afterDeclarations` options.
Demonstrates how typescript-transform-paths conceptually integrates with the TypeScript compilation process, showing a basic setup for transforming both `.js` and `.d.ts` files based on `tsconfig.json` paths.
import * as fs from 'fs';
import * as path from 'path';
import * as ts from 'typescript';
// Minimal ts-patch setup for demonstration
const tsconfigPath = path.resolve('./tsconfig.json');
const tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');
const tsconfig = ts.parseConfigFileTextToJson(tsconfigPath, tsconfigContent).config;
// Simulate the ts-patch application of the transformer
// In a real setup, ts-patch handles this with its CLI tool.
const program = ts.createProgram({
rootNames: [path.resolve('./src/index.ts')],
options: {
...tsconfig.compilerOptions,
noEmit: false, // Ensure output for demonstration
outDir: './dist-quickstart' // Output to a specific directory
},
});
const emitResult = program.emit(undefined, undefined, undefined, undefined, [
{
before: (ctx) => (sourceFile) => {
// This represents the 'typescript-transform-paths' plugin
// In real scenarios, this is loaded dynamically by ts-patch
const ttPaths = require('typescript-transform-paths');
const transformer = ttPaths.default(program, tsconfig.compilerOptions, {}, ts, path, fs)(ctx);
return transformer(sourceFile);
},
afterDeclarations: (ctx) => (sourceFile) => {
const ttPaths = require('typescript-transform-paths');
const transformer = ttPaths.default(program, tsconfig.compilerOptions, { afterDeclarations: true }, ts, path, fs)(ctx);
return transformer(sourceFile);
}
}
]);
if (emitResult.emitSkipped) {
console.log('Compilation failed or skipped.');
} else {
console.log('Compilation successful. Check ./dist-quickstart for output.');
}
/*
To run this:
1. Create tsconfig.json:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@utils/*": ["./src/utils/*"]
},
"outDir": "./dist",
"declaration": true,
"target": "es2018",
"module": "commonjs",
"strict": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"plugins": [
{ "transform": "typescript-transform-paths" },
{ "transform": "typescript-transform-paths", "afterDeclarations": true }
]
},
"include": ["src/**/*.ts"]
}
2. Create src/utils/sum.ts:
export function sum(a: number, b: number): number { return a + b; }
3. Create src/index.ts:
import { sum } from "@utils/sum";
console.log(sum(1, 2));
4. Install deps: npm i -D typescript typescript-transform-paths
5. Run with `npx ts-node your-script.ts` (this script simulates the plugin, not directly using ts-patch CLI)
(For actual usage, you'd run `npx ts-patch tsc` after `ts-patch install`)
*/
Errors
Common errors & fixes
TypeError: (0 , typescript_transform_paths_1.default) is not a function
Attempting to `import` or `require` the plugin directly in application code, or an incorrect setup with `ts-patch` or `ts-node`.
fixThis package is a compiler plugin, not a runtime library for direct import. Ensure it's correctly configured in `tsconfig.json` `plugins` for compilation (with `ts-patch`) or used via its `register` script for runtime (`node -r` or `ts-node` config).
Error: Expected version to be parsed
This error occurs in specific scenarios where the installed TypeScript version string contains a '0' in an unexpected position, causing issues with internal version parsing logic.
fixThis was fixed in v3.5.5. Update `typescript-transform-paths` to version 3.5.5 or newer to resolve this parsing issue.
Module not found: Error: Can't resolve '@utils/sum' in '...' (or similar path alias error after build)
The TypeScript `paths` configuration was not transformed during compilation, or the runtime environment is not resolving the aliased paths.
fixVerify that `typescript-transform-paths` is correctly configured in your `tsconfig.json` plugins for both `.js` and `.d.ts` files. If compiling with `tsc`, ensure `ts-patch install` and `ts-patch tsc` are used. If at runtime, make sure `typescript-transform-paths/register` is active (e.g., `node -r` or `ts-node` config).
Audit
Dependencies
typescriptrequiredPeer dependency, required for compilation and type checking functionalities. Version >=3.6.5 is explicitly stated.