This content originally appeared on DEV Community and was authored by Vedhashree Sampath
If you’ve worked on a TypeScript project of any size, you’ve probably found yourself tangled in a web of relative import hell:
import { UserService } from '../../../services/user';
It’s not just ugly — it’s hard to manage, especially when the project grows. Luckily, TypeScript Path Aliases come to the rescue. And even better, the ts-path-alias-fixer npm package can help you automatically migrate your entire codebase from relative imports to clean, manageable alias paths.
In this post, we’ll break down:
- What path aliases are
- How to set them up in TypeScript
- How to use ts-path-alias-fixer to refactor existing code
📌 What Are TypeScript Path Aliases?
Path aliases let you define custom names for directories in your project. So instead of this:
import { ProductService } from '../../../../core/services/ProductService';
You can do this:
import { ProductService } from '@core/services/ProductService';
Much cleaner, right?
🔧 Setting Up Path Aliases in TypeScript
To define path aliases, you need to tweak your tsconfig.json.
{
"compilerOptions": {
"baseUrl": "./src",
"paths": {
"@components/*": ["components/*"],
"@utils/*": ["utils/*"],
"@core/*": ["core/*"]
}
}
}
Breakdown:
-
baseUrl: The root directory for all your imports (usuallysrc) -
paths: An object where keys are aliases and values are actual paths relative tobaseUrl
Make sure your tooling (Webpack, Jest, etc.) also understands these aliases. That’s outside this post’s scope, but worth noting.
🤖 Meet ts-path-alias-fixer: Your Import Refactoring Bot
Refactoring all those ../../../ imports manually? No thanks.
ts-path-alias-fixer is a CLI tool that scans your project and replaces relative imports with your configured path aliases — in seconds.
✅Key Benefits:
- No manual work
- Preview changes using--dry-run option without modifying files
- Fast and safe
- Works recursively across folders
⚙️ Installing and Using ts-path-alias-fixer
Step 1: Install the package
Global Install
npm install -g ts-path-alias-fixer
Local Install (recommended)
Install as a development dependency in your project:
with npm:
npm install --save-dev ts-path-alias-fixer
or with Yarn:
yarn add --dev ts-path-alias-fixer
Step 2: Define Path Aliases in tsconfig.json
Make sure your tsconfig.json includes baseUrl and paths, like we saw earlier.
Example:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/lib/apiClient/components/*"],
"@services/*": ["src/lib/apiClient/services/*"],
"@utils/*": ["src/utils/*"]
}
}
}
or
{
"compilerOptions": {
"baseUrl": "./src",
"paths": {
"@services/*": ["services/*"],
"@models/*": ["models/*"]
}
}
}
Step 3: Run the Fixer
From your project root, run with or without optional cli flags as described below:
npx fix-ts-imports
It will scan all .ts and .tsx files, detect relative imports, and replace them with the corresponding path aliases based on your tsconfig.json settings.
🛠️ Optional CLI Flags
Some useful options you can use:
--dir: Specify your project root directory e.g ./
--alias : Specify the alias to replace relative paths with e.g @
--base: Base folder path inside the project to replace e.g src
--dry-run: Preview changes without modifying files
Example:
If you just want to change all the files with relative imports as ../.. to be replaced with custom alias with the base directory like @/
to convert the following import line
import { ProductService } from '../../../../core/services/ProductService';
to :
import { ProductService } from '@/core/services/ProductService';
You can do this:
npx fix-ts-imports
or
with optional args as
npx fix-ts-imports --dir ./ --alias @ --base src
Note: Here src is the dir path given as --base path for alias to be used that is defined as paths in tsconfig.json file as given in the example for @/*
{
...
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
}
...
}
or
{
...,
"baseUrl": "./src",
"paths": {
"@/*": ["/*"],
...,
}
🧪 Before & After Example
Example tsconfig.json file in your project
Example:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/lib/apiClient/components/*"],
"@services/*": ["src/lib/apiClient/services/*"],
"@utils/*": ["src/utils/*"]
},
}
}
Want to modify just all relative path imports like ../.. in your project directory to a common base custom alias path like @/
Before:
import { ApiService } from '../../../services/ApiService';
After running ts-path-alias-fixer:
Run the below from your command line
npx fix-ts-imports --dir ./ --alias @ --base src
and your files will get converted to
import { ApiService } from '@/services/ApiService';
Want to modify all project files with all relative path imports related to services like ../../src/lib/apiClient/services/service-1 in your project directory to a custom directory alias path like @services/
Before:
import { ApiService } from '../../../../services/ApiService';
After running ts-path-alias-fixer:
Run the below from your command line
npx fix-ts-imports --dir ./ --alias @services --base src/lib/apiClient/services
and your files will get converted to
import { ApiService } from '@services/ApiService';
Want to modify again now, with all project files with all relative path imports related to components like ../../src/lib/apiClient/components/component-1 in your project directory to a custom directory alias path like @components/
Before:
import { Button} from '../../../../components/buttonComponent';
After running ts-path-alias-fixer:
Run the below from your command line
npx fix-ts-imports --dir ./ --alias @components --base src/lib/apiClient/components
and your files will get converted to
import { Button} from '@components/buttonComponent';
Use this tool like as many times as you like and in minutes enjoy a much cleaner and readable code.
Run with dry-run option:
In your project, before modifying your existing files by using this tool, if you want to check and understand what files will get affected
Preview changes without modifying files:
npx fix-ts-imports --dry-run
Run with custom options:
npx fix-ts-imports --dir ./src --alias @ --base src --dry-run
Example Output
Once you run the cli command as above with dry-run, You should see console logs indicating how many files would be modified, along with their file paths, like below:
🔍 Dry run: 3 file(s) would be modified.
- src\index.ts
- src\utils\helper.ts
- src\api\v1\index.ts
After you are happy with the --dry-run option output, run the cli command without --dry-run option to modify the files.
🛡️ Tips & Best Practices
- Always commit your code before running the tool — just in case
- Use the
--dry-runoption to preview changes - Add path aliases early in a project to avoid future refactors
- Combine with ESLint rules to enforce alias usage in teams
🚀 Wrapping Up
Using TypeScript Path Aliases makes your codebase cleaner, more maintainable, and scalable. With the power of ts-path-alias-fixer, you can automate the migration and focus on writing code instead of counting ../../.
So go ahead — install it, alias your paths, and thank yourself later. 🧠
💬 Got Questions or Tips?
Drop them in the comments! And if this helped you, consider sharing it with your team or giving the repo a ⭐️ on GitHub.
Original Content link : "https://medium.com/@shreevedhas/mastering-typescript-path-aliases-with-ts-path-alias-fixer-be3184778e7b"
Happy coding! 👨💻👩💻
This content originally appeared on DEV Community and was authored by Vedhashree Sampath
Vedhashree Sampath | Sciencx (2025-09-20T15:06:11+00:00) 🚀 Simplifying imports by TypeScript Path Aliases with `ts-path-alias-fixer`. Retrieved from https://www.scien.cx/2025/09/20/%f0%9f%9a%80-simplifying-imports-by-typescript-path-aliases-with-ts-path-alias-fixer/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.