tsc-alias

library1.8.16jsnpmunverified

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.

devops

npm install tsc-alias

github ↗package ↗

INSTALL

IMPORT

SIG · TSC-ALIAS

tsc-alias

devopsjavascriptv1.8.16

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

replaceTscAliasPaths

✓ import { replaceTscAliasPaths } from 'tsc-alias';

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

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

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

tsc-alias --version

Debug

Known issues

deprecatedThe `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.

affects: >=1.8.0

gotchatsc-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`.

affects: >=1.0.0

breakingEarlier 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.

affects: <1.8.13

gotchaWhen 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`.

affects: <1.8.14

gotchaTypeScript 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).

affects: >=1.8.12

Errors

Common errors & fixes

Error: compilerOptions.outDir is not set

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'

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

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>'

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.

Upgrade

Version history

1.8.16latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/justkey007/tsc-alias ↗

packagehttps://www.npmjs.com/package/tsc-alias ↗