{"id":12260,"library":"typescript-transform-paths","title":"TypeScript Path Mapping Transformer","description":"typescript-transform-paths is a TypeScript compiler plugin that transforms module resolution paths defined in `tsconfig.json`'s `paths` or `rootDirs` options into correct relative paths within the compiled JavaScript and declaration files. It addresses a common pain point where TypeScript's path aliases are not natively resolved by Node.js or bundlers without additional configuration. The current stable version is 3.5.6, with a significant v4.0.0-beta release that transitions to ESM-only. The package sees regular maintenance releases and active development, with a beta channel for upcoming major changes. Its key differentiators include comprehensive support for both `.js` and `.d.ts` file transformations, integration with various build tools like `ts-patch`, `ts-node`, `node -r`, and NX, and the ability to define exclusion patterns for granular control.","status":"active","version":"3.5.6","language":"javascript","source_language":"en","source_url":"https://github.com/LeDDGroup/typescript-transform-paths","tags":["javascript","typescript","transform","transformer","plugin","path","paths","virtual directory","import"],"install":[{"cmd":"npm install typescript-transform-paths","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-transform-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-transform-paths","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for compilation and type checking functionalities. Version >=3.6.5 is explicitly stated.","package":"typescript","optional":false}],"imports":[{"note":"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`.","wrong":"import * as transform from 'typescript-transform-paths'","symbol":"transformer","correct":"{ \"transform\": \"typescript-transform-paths\" }"},{"note":"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.","wrong":"{ \"transform\": \"typescript-transform-paths/afterDeclarations\" }","symbol":"afterDeclarations transformer","correct":"{ \"transform\": \"typescript-transform-paths\", \"afterDeclarations\": true }"},{"note":"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.","wrong":"require('typescript-transform-paths/register')","symbol":"register","correct":"node -r typescript-transform-paths/register your-app.js"},{"note":"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.","symbol":"nx-transformer","correct":"{ \"name\": \"typescript-transform-paths/nx-transformer\" }"}],"quickstart":{"code":"import * as fs from 'fs';\nimport * as path from 'path';\nimport * as ts from 'typescript';\n\n// Minimal ts-patch setup for demonstration\nconst tsconfigPath = path.resolve('./tsconfig.json');\nconst tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');\nconst tsconfig = ts.parseConfigFileTextToJson(tsconfigPath, tsconfigContent).config;\n\n// Simulate the ts-patch application of the transformer\n// In a real setup, ts-patch handles this with its CLI tool.\nconst program = ts.createProgram({\n  rootNames: [path.resolve('./src/index.ts')],\n  options: {\n    ...tsconfig.compilerOptions,\n    noEmit: false, // Ensure output for demonstration\n    outDir: './dist-quickstart' // Output to a specific directory\n  },\n});\n\nconst emitResult = program.emit(undefined, undefined, undefined, undefined, [\n  {\n    before: (ctx) => (sourceFile) => {\n      // This represents the 'typescript-transform-paths' plugin\n      // In real scenarios, this is loaded dynamically by ts-patch\n      const ttPaths = require('typescript-transform-paths');\n      const transformer = ttPaths.default(program, tsconfig.compilerOptions, {}, ts, path, fs)(ctx);\n      return transformer(sourceFile);\n    },\n    afterDeclarations: (ctx) => (sourceFile) => {\n      const ttPaths = require('typescript-transform-paths');\n      const transformer = ttPaths.default(program, tsconfig.compilerOptions, { afterDeclarations: true }, ts, path, fs)(ctx);\n      return transformer(sourceFile);\n    }\n  }\n]);\n\nif (emitResult.emitSkipped) {\n  console.log('Compilation failed or skipped.');\n} else {\n  console.log('Compilation successful. Check ./dist-quickstart for output.');\n}\n\n/*\n  To run this:\n  1. Create tsconfig.json:\n     {\n       \"compilerOptions\": {\n         \"baseUrl\": \".\",\n         \"paths\": {\n           \"@utils/*\": [\"./src/utils/*\"]\n         },\n         \"outDir\": \"./dist\",\n         \"declaration\": true,\n         \"target\": \"es2018\",\n         \"module\": \"commonjs\",\n         \"strict\": true,\n         \"esModuleInterop\": true,\n         \"forceConsistentCasingInFileNames\": true,\n         \"plugins\": [\n           { \"transform\": \"typescript-transform-paths\" },\n           { \"transform\": \"typescript-transform-paths\", \"afterDeclarations\": true }\n         ]\n       },\n       \"include\": [\"src/**/*.ts\"]\n     }\n  2. Create src/utils/sum.ts:\n     export function sum(a: number, b: number): number { return a + b; }\n  3. Create src/index.ts:\n     import { sum } from \"@utils/sum\";\n     console.log(sum(1, 2));\n  4. Install deps: npm i -D typescript typescript-transform-paths\n  5. Run with `npx ts-node your-script.ts` (this script simulates the plugin, not directly using ts-patch CLI)\n     (For actual usage, you'd run `npx ts-patch tsc` after `ts-patch install`)\n*/\n","lang":"typescript","description":"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."},"warnings":[{"fix":"For CommonJS projects, remain on `typescript-transform-paths@3.x`. For new projects or migration, ensure your `tsconfig.json` sets `\"module\": \"esnext\"` or similar, and update your build tools to handle ESM.","message":"Version 4.0.0-beta introduces an ESM-only distribution. Projects targeting CommonJS modules will need to stick to version 3.x or migrate their build system to ESM.","severity":"breaking","affected_versions":">=4.0.0-beta"},{"fix":"Add both `{\"transform\": \"typescript-transform-paths\"}` and `{\"transform\": \"typescript-transform-paths\", \"afterDeclarations\": true}` to your `compilerOptions.plugins` array.","message":"To ensure path transformations apply to both compiled JavaScript (`.js`) files and their corresponding TypeScript declaration (`.d.ts`) files, you must include two separate plugin entries in your `tsconfig.json`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In your `tsconfig.json`, within the `ts-node` configuration block, add `\"require\": [\"typescript-transform-paths/register\"]`.","message":"When using `typescript-transform-paths` with `ts-node`, it's important to configure `ts-node` to `require` the transformation module. Simply having the plugin in `tsconfig.json` does not automatically enable it for `ts-node`'s runtime compilation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For `tsc` compilation, install and use `ts-patch` (`ts-patch install` then `ts-patch tsc`). For runtime, use `node -r typescript-transform-paths/register` or configure `ts-node` accordingly.","message":"The plugin needs to be applied by a TypeScript transformer runner. Installing the package alone is not enough; you must integrate it with a tool like `ts-patch` for `tsc` compilation or use its `register` script for runtime.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure your `typescript` peer dependency meets the specified requirements and consider updating `typescript-transform-paths` to the latest stable version to benefit from compatibility fixes.","message":"Older TypeScript versions (e.g., prior to 3.6.5, though the peer dep is now >=3.6.5) or specific patch versions might lead to compatibility issues, as observed with `minimatch` dependency changes and TypeScript 5.6 compatibility fixes.","severity":"gotcha","affected_versions":"<3.5.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This 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).","cause":"Attempting to `import` or `require` the plugin directly in application code, or an incorrect setup with `ts-patch` or `ts-node`.","error":"TypeError: (0 , typescript_transform_paths_1.default) is not a function"},{"fix":"This was fixed in v3.5.5. Update `typescript-transform-paths` to version 3.5.5 or newer to resolve this parsing issue.","cause":"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.","error":"Error: Expected version to be parsed"},{"fix":"Verify 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).","cause":"The TypeScript `paths` configuration was not transformed during compilation, or the runtime environment is not resolving the aliased paths.","error":"Module not found: Error: Can't resolve '@utils/sum' in '...' (or similar path alias error after build)"}],"ecosystem":"npm"}