Home Original page

GitHub - LeDDGroup/typescript-transform-paths: Transforms module resolution paths using TypeScript path mapping and/or custom paths

Transform compiled source module resolution paths using TypeScript's paths config, and/or custom resolution paths

npm version Build Status Conventional Commits Code Style: Prettier

Tip

Upgrading from v3 to v4? See the migration documentation.

Setup Steps

1. Install

<yarn|npm|pnpm> add -D typescript-transform-paths

2. Configure

Add it to plugins in your tsconfig.json file.

Example Configuration

Example Result

core/index.ts

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

3. Use

  • Compile with tsc — Use ts-patch.

  • Run with ts-node — See the Wiki.

  • Integrate with Nx — Add the typescript-transform-paths/plugins/nx transformer to the project configuration.

    project.json

Virtual Directories

TypeScript allows defining Virtual Directories via the rootDirs compiler option.
To enable Virtual Directory mapping, use the useRootDirs plugin option.

tsconfig.json

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 those resolved file paths.

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

tsconfig.json

// This path will NOT be transformed
import * as sm1 from "sub-module1/index";

@transform-path

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 defined 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 Node.js
^4.0.0 >=5.x >=22
^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

Maintainers