TypeScript Alias Path Replacer

1.8.16 · active · verified Sun Apr 19

tsc-alias is a utility designed to resolve TypeScript's `paths` aliases into relative paths *after* TypeScript compilation has completed. This ensures that the compiled JavaScript files can be run directly without requiring additional runtime modules like `tsconfig-paths`, distinguishing it through its compile-time-only approach. The package is currently at version `1.8.16` (as of May 2025) and maintains an active release cadence with frequent patches addressing compatibility and bug fixes. It is typically integrated into `package.json` build scripts alongside `tsc`, providing a robust solution for managing complex module import structures in both Node.js and browser environments. It ships with TypeScript types and requires Node.js `^16.20.2` or later.

Common errors

```
Error: compilerOptions.outDir is not set
```
cause Your `tsconfig.json` file is missing the `compilerOptions.outDir` property, or `tsc-alias` is unable to correctly parse your configuration.

fix Add `"outDir": "./dist"` (or your desired output directory) to your `compilerOptions` in `tsconfig.json`. Ensure the `--project` (`-p`) flag is correctly pointing to your `tsconfig.json`.
```
ReferenceError: Cannot find module '@alias/module'
```
cause This error occurs when running the compiled JavaScript, indicating that `tsc-alias` either was not run, or failed to correctly replace the alias paths after TypeScript compilation.

fix Verify that `tsc-alias` is properly integrated into your build script (e.g., `"build": "tsc && tsc-alias"`). Check your `tsconfig.json`'s `compilerOptions.paths` to ensure aliases are correctly defined and match your import statements.
```
Error: No aliases found in tsconfig.json for project: tsconfig.json
```
cause The specified `tsconfig.json` file does not contain a `compilerOptions.paths` configuration, or the `paths` object is empty.

fix Add or verify `compilerOptions.paths` in your `tsconfig.json` with valid alias mappings, for example: `"paths": { "@app/*": ["src/app/*"] }`.
```
Error: ENOENT: no such file or directory, stat '<path-to-file>'
```
cause tsc-alias is trying to process a file that doesn't exist, often due to an incorrect `outDir` in `tsconfig.json` or misconfigured input glob patterns.

fix Double-check your `tsconfig.json`'s `compilerOptions.outDir` to ensure it points to the correct compiled JavaScript output directory. If using `--inputglob`, verify the pattern matches existing files.

Warnings

deprecated The `silent` option, previously available in both CLI and API, is deprecated and no longer has any effect on terminal output.
Fix: Remove the `--silent` flag from CLI commands or the `silent` property from API options. Use `verbose` or `debug` for controlling output.
gotcha tsc-alias must be executed *after* TypeScript compilation (`tsc`) completes. Running it before `tsc` will result in no path replacements, as the JavaScript output files will not yet exist.
Fix: Ensure your build script correctly orders `tsc` before `tsc-alias`, typically using `&&` for sequential execution, e.g., `tsc && tsc-alias`.
breaking Earlier versions of tsc-alias had compatibility issues with Node.js 20+. Users on these older versions might encounter errors related to Node.js environment.
Fix: Upgrade tsc-alias to version `1.8.13` or newer to ensure full compatibility with Node.js 20+ environments.
gotcha When using `tsc-alias` with `tsconfig.json` files that extend other configuration files, ensure the primary `tsconfig.json` is correctly passed, as previous versions had issues resolving paths from extended configs.
Fix: Upgrade to tsc-alias v1.8.14 or newer. Always explicitly pass the project config with `-p tsconfig.json`.
gotcha TypeScript declaration files (`.d.ts`) are intentionally not processed for alias replacement since version `1.8.12` to maintain type integrity. If you observed replacements in `.d.ts` files prior to this version, that behavior has changed.
Fix: This is expected and desired behavior. No fix is required unless you had a specific, non-standard workflow relying on `.d.ts` replacement (which is generally not recommended).

Install

npm install tsc-alias npm
yarn add tsc-alias yarn
pnpm add tsc-alias pnpm

Imports

replaceTscAliasPaths

wrong:

const replaceTscAliasPaths = require('tsc-alias').replaceTscAliasPaths;

correct:

import { replaceTscAliasPaths } from 'tsc-alias';

Primarily a CLI tool, this is the main programmatic entry point for API usage.

Quickstart

Demonstrates how to configure and run `tsc-alias` with TypeScript aliases in a build script.

{
  "name": "tsc-alias-example",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc --project tsconfig.json && tsc-alias -p tsconfig.json",
    "start": "npm run build && node dist/index.js"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "tsc-alias": "^1.8.16"
  }
}
// Save as package.json

// ------------------------------------------------------------------

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "baseUrl": "./src",
    "paths": {
      "@utils/*": ["utils/*"],
      "@config": ["config.ts"]
    },
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts", "src/**/*.json"]
}
// Save as tsconfig.json

// ------------------------------------------------------------------

// src/config.ts
export const appName = "My Tsc-Alias App";

// src/utils/helper.ts
export const greet = (name: string) => `Hello, ${name}!`;

// src/index.ts
import { greet } from '@utils/helper'; // Using an alias
import { appName } from '@config';     // Another alias

console.log(`${greet('World')} from ${appName}!`);
// Save these as src/config.ts, src/utils/helper.ts, src/index.ts

// ------------------------------------------------------------------

// After saving the files, run in your terminal:
// npm install
// npm run start

view raw JSON →