typescript-transform-paths

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-paths

2. 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-patch

• Use with ts-node — Add typescript-transform-paths/register to require config.

  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.ts

• Use with NX — Add the typescript-transform-paths/nx-transformer to project config

  project.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.ts

src/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 config

Version 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 release

Alternatives

• NodeJS subpath imports
• Yarn link: protocol

Maintainers

Ron S.

Daniel Perez Alvarez

Changelog

v3.5.3

compare changes

📖 Documentation

• Add version compatibility matrix in readme (#338)

🏡 Chore

• deps-dev: Bump @eslint/js from 9.9.1 to 9.15.0 (#310)
• deps-dev: Bump typescript-eslint from 8.13.0 to 8.15.0 (#308)
• deps-dev: Bump eslint from 9.10.0 to 9.15.0 (#309)
• deps-dev: Bump changelogen from 0.5.5 to 0.5.7 (#316)
• deps-dev: Bump @types/node from 22.8.7 to 22.9.3 (#314)
• deps-dev: Bump typescript from 5.6.3 to 5.7.2 in /test (#317)
• deps-dev: Bump typescript-eslint from 8.15.0 to 8.16.0 (#313)
• deps-dev: Bump eslint from 9.15.0 to 9.16.0 (#319)
• deps-dev: Bump typescript-eslint from 8.16.0 to 8.17.0 (#320)
• deps-dev: Update yarn from 4.4.0 to 4.5.3 (f6ccab1)
• Update yarn.lock (b958778)
• deps-dev: Bump ts-patch from 3.2.1 to 3.3.0 (#322)
• deps-dev: Bump typescript-eslint from 8.17.0 to 8.18.0 (#323)
• deps-dev: Bump typescript from 5.5.4 to 5.7.2 (#315)
• deps-dev: Bump ts-patch from 3.2.1 to 3.3.0 in /test (#324)
• Configure Renovate (#330)
• Update renovate config to auto merge minor updates (b3f3f31)

🤖 CI

• Adjust publish workflow (1039e07)
• Fix changelogen not pushing code (221136a)

❤️ Contributors

• Daniel Perez Alvarez [e-mail]