typescript-transform-paths
    TypeScript icon, indicating that this package has built-in type declarations

    3.3.1 • Public • Published

    typescript-transform-paths

    npm version Build Status Conventional Commits code style: prettier All Contributors

    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

    • To compile with tsc — Use ts-patch

    • To use with ts-node — Add typescript-trasnsform-paths/register to require config.

      tsconfig.json

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

    Articles

    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

    Install

    npm i typescript-transform-paths

    DownloadsWeekly Downloads

    38,025

    Version

    3.3.1

    License

    MIT

    Unpacked Size

    78.2 kB

    Total Files

    32

    Last publish

    Collaborators

    • danielpanpm
    • nonara