TypeScript Path Mapping Transformer

3.5.6 · active · verified Sun Apr 19

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.

Common errors

Warnings

Install

Imports

Quickstart

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`)
*/

view raw JSON →