typescript-transform-paths

Transform compiled source module resolution paths using TypeScript's

paths

Setup Steps

1. Install

 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

tsx
// The following transforms path to '../utils/sum'
import { sum } from "@utils/sum";

3. Usage

• To compile with

  tsc

  — Use ts-patch

• To use with ts-node — Add

  typescript-trasnsform-paths/register

  to

  require

  config.

  tsconfig.json

  jsonc
  {
  "ts-node": {
    "transpileOnly": true,
    "require": [ "typescript-transform-paths/register" ],
  },
  "compilerOptions" { /* ... */ }
  }
  

• To use with node — Use the register script:

  node -r typescript-transform-paths/register src/index.ts

Virtual Directories

TS allows defining virtual directories via the

rootDirs

useRootDirs

{
  "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

ts
import '#root/file2.ts' // resolves to './file2'

src/subdir/sub-file.ts

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

For an example context in which this would be useful, see Issue #83

Example:

jsonc
{
  "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

// @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

// @no-transform-path
import 'normally-transformed' // This will remain 'normally-transformed', even though it has a different value in paths config

Articles

• Node Consumable Modules With Typescript Paths by oleersoy

Project Guidelines for Contributors

• Package Manager:

  yarn

  (

  yarn install

  )
• Commit messages: Conventional Commit Specs
• Format before commit:

  prettier

  (

  yarn run format

  )
• Releases:

  standard-version

  (

  yarn run release

  )

Maintainers

Ron S.

Daniel Perez Alvarez