{"id":12190,"library":"tsc-alias","title":"TypeScript Alias Path Replacer","description":"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.","status":"active","version":"1.8.16","language":"javascript","source_language":"en","source_url":"https://github.com/justkey007/tsc-alias","tags":["javascript","typescript","paths","alias","absolute path","relative path","compilation","tsc"],"install":[{"cmd":"npm install tsc-alias","lang":"bash","label":"npm"},{"cmd":"yarn add tsc-alias","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsc-alias","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily a CLI tool, this is the main programmatic entry point for API usage.","wrong":"const replaceTscAliasPaths = require('tsc-alias').replaceTscAliasPaths;","symbol":"replaceTscAliasPaths","correct":"import { replaceTscAliasPaths } from 'tsc-alias';"}],"quickstart":{"code":"{\n  \"name\": \"tsc-alias-example\",\n  \"version\": \"1.0.0\",\n  \"main\": \"dist/index.js\",\n  \"scripts\": {\n    \"build\": \"tsc --project tsconfig.json && tsc-alias -p tsconfig.json\",\n    \"start\": \"npm run build && node dist/index.js\"\n  },\n  \"devDependencies\": {\n    \"typescript\": \"^5.0.0\",\n    \"tsc-alias\": \"^1.8.16\"\n  }\n}\n// Save as package.json\n\n// ------------------------------------------------------------------\n\n{\n  \"compilerOptions\": {\n    \"target\": \"es2020\",\n    \"module\": \"commonjs\",\n    \"outDir\": \"./dist\",\n    \"baseUrl\": \"./src\",\n    \"paths\": {\n      \"@utils/*\": [\"utils/*\"],\n      \"@config\": [\"config.ts\"]\n    },\n    \"esModuleInterop\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"strict\": true,\n    \"skipLibCheck\": true\n  },\n  \"include\": [\"src/**/*.ts\", \"src/**/*.json\"]\n}\n// Save as tsconfig.json\n\n// ------------------------------------------------------------------\n\n// src/config.ts\nexport const appName = \"My Tsc-Alias App\";\n\n// src/utils/helper.ts\nexport const greet = (name: string) => `Hello, ${name}!`;\n\n// src/index.ts\nimport { greet } from '@utils/helper'; // Using an alias\nimport { appName } from '@config';     // Another alias\n\nconsole.log(`${greet('World')} from ${appName}!`);\n// Save these as src/config.ts, src/utils/helper.ts, src/index.ts\n\n// ------------------------------------------------------------------\n\n// After saving the files, run in your terminal:\n// npm install\n// npm run start","lang":"typescript","description":"Demonstrates how to configure and run `tsc-alias` with TypeScript aliases in a build script."},"warnings":[{"fix":"Remove the `--silent` flag from CLI commands or the `silent` property from API options. Use `verbose` or `debug` for controlling output.","message":"The `silent` option, previously available in both CLI and API, is deprecated and no longer has any effect on terminal output.","severity":"deprecated","affected_versions":">=1.8.0"},{"fix":"Ensure your build script correctly orders `tsc` before `tsc-alias`, typically using `&&` for sequential execution, e.g., `tsc && tsc-alias`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade tsc-alias to version `1.8.13` or newer to ensure full compatibility with Node.js 20+ environments.","message":"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.","severity":"breaking","affected_versions":"<1.8.13"},{"fix":"Upgrade to tsc-alias v1.8.14 or newer. Always explicitly pass the project config with `-p tsconfig.json`.","message":"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.","severity":"gotcha","affected_versions":"<1.8.14"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.8.12"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Your `tsconfig.json` file is missing the `compilerOptions.outDir` property, or `tsc-alias` is unable to correctly parse your configuration.","error":"Error: compilerOptions.outDir is not set"},{"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.","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.","error":"ReferenceError: Cannot find module '@alias/module'"},{"fix":"Add or verify `compilerOptions.paths` in your `tsconfig.json` with valid alias mappings, for example: `\"paths\": { \"@app/*\": [\"src/app/*\"] }`.","cause":"The specified `tsconfig.json` file does not contain a `compilerOptions.paths` configuration, or the `paths` object is empty.","error":"Error: No aliases found in tsconfig.json for project: tsconfig.json"},{"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.","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.","error":"Error: ENOENT: no such file or directory, stat '<path-to-file>'"}],"ecosystem":"npm"}