🚀 Simplifying imports by TypeScript Path Aliases with `ts-path-alias-fixer`

Vedhashree Sampath — Sat, 20 Sep 2025 15:06:11 +0000

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 (usually src)
paths: An object where keys are aliases and values are actual paths relative to baseUrl

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/*"]
    }
  }
}

{
  "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

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/*"],
      }
...
}

{
...,
"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-run option 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! 👨‍💻👩‍💻

DEV Community: Vedhashree Sampath

🚀 Simplifying imports by TypeScript Path Aliases with `ts-path-alias-fixer`

📌 What Are TypeScript Path Aliases?

🔧 Setting Up Path Aliases in TypeScript

Breakdown:

🤖 Meet ts-path-alias-fixer: Your Import Refactoring Bot

⚙️ Installing and Using ts-path-alias-fixer

Step 1: Install the package

Step 2: Define Path Aliases in tsconfig.json

Step 3: Run the Fixer

🛠️ Optional CLI Flags

🧪 Before & After Example

Run with dry-run option:

Preview changes without modifying files:

🛡️ Tips & Best Practices

🚀 Wrapping Up

💬 Got Questions or Tips?

⚙️ Installing and Using `ts-path-alias-fixer`

Step 2: Define Path Aliases in `tsconfig.json`