tsc-alias

You can install tsc-alias either globally or as a development dependency in your project.

To install globally:

npm install -g tsc-alias

To install as a devDependency (recommended):

npm install --save-dev tsc-alias

To use tsc-alias in your workflow, add it to your package.json scripts after the TypeScript compilation step (tsc). This ensures that alias paths are replaced with relative paths in the compiled output.

Standard build script:

"scripts": {
  "build": "tsc --project tsconfig.json && tsc-alias -p tsconfig.json"
}

Watch mode (using concurrently): If you want to watch for changes in both TypeScript and your aliases, you can use concurrently:

"scripts": {
  "build:watch": "tsc && (concurrently \"tsc -w\" \"tsc-alias -w\")"
}

"scripts": {
  "build": "tsc --project tsconfig.json && tsc-alias -p tsconfig.json",
}

You can provide configuration for tsc-alias directly within your tsconfig.json file using a tsc-alias key. This is useful for setting up advanced options like custom replacers or file extension patterns.

{
  "compilerOptions": {
    ...
  },
  "tsc-alias": {
    "verbose": false,
    "resolveFullPaths": true,
    "replacers": {
      "exampleReplacer": {
        "enabled": true,
        "file": "./exampleReplacer.js"
      },
      "otherReplacer": {
        "enabled": true,
        "file": "./otherReplacer.js"
      }
    },
    "fileExtensions": {
      "inputGlob": "{js,jsx,mjs}",
      "outputCheck": ["js", "json", "jsx", "mjs"]
    }
  }
}

A regression in tsc-alias version 1.9.0 causes issues when a source file has the same name as an npm package it imports. If you have a file named src/redis.ts and you import from the redis npm package, tsc-alias 1.9.0 may incorrectly rewrite the import to a relative path pointing to the file itself (require("./redis")) instead of the npm package. This causes the module to require itself, leading to runtime errors like TypeError: (0 , redis_1.createClient) is not a function because the named export becomes undefined.

// src/redis.ts
import { createClient } from 'redis'; // This may be incorrectly rewritten to './redis'
const client = createClient();

To reproduce the bug where bare module specifiers are incorrectly rewritten to relative paths, use the following steps in an environment with tsc-alias 1.9.0 and TypeScript 6.0+ where tsconfig.json defines paths but lacks a baseUrl:

1. Install dependencies: npm install
2. Build the project: npm run build (which executes tsc --noCheck && tsc-alias)
3. Check the compiled output: grep require dist/redis.js
4. Run the output: node ./dist/redis.js

npm install
npm run build          # tsc --noCheck && tsc-alias
grep require dist/redis.js
# Expected error output: const redis_1 = require("./redis");

node ./dist/redis.js
# Expected error: TypeError: (0 , redis_1.createClient) is not a function

You can programmatically replace alias paths using the replaceTscAliasPaths function. This function accepts an optional configuration object.

import { replaceTscAliasPaths } from 'tsc-alias';

replaceTscAliasPaths(options?);

If you need to perform alias replacement on specific file contents manually (for example, within a custom build pipeline or a virtual file system), use prepareSingleFileReplaceTscAliasPaths.

This function returns a SingleFileReplacer function. You call this returned function with an object containing the fileContents and the filePath to get the transformed string back.

Usage Pattern:

1. Call prepareSingleFileReplaceTscAliasPaths(options) to get the replacer function.
2. Invoke the replacer with { fileContents, filePath }.

import { prepareSingleFileReplaceTscAliasPaths } from 'tsc-alias';

const replacer = await prepareSingleFileReplaceTscAliasPaths({
  // your options here
});

const transformedContent = replacer({
  fileContents: 'import { something } from "@alias/module";',
  filePath: '/path/to/file.ts'
});
// transformedContent will have the alias replaced

You can intercept and modify how import statements are rewritten by providing custom replacers. An AliasReplacer is a function that receives AliasReplacerArguments and returns the new import string.

AliasReplacerArguments contains:

• orig: The original import statement string.
• file: The path of the file being processed.
• config: The current IConfig object.

Additionally, you can use ReplacerOptions to enable or disable specific replacers, optionally scoped to a specific file.

export type AliasReplacer = (args: AliasReplacerArguments) => string;

export interface AliasReplacerArguments {
  orig: string;
  file: string;
  config: IConfig;
}

export interface ReplacerOptions {
  [key: string]: {
    enabled: boolean;
    file?: string;
  };
}