DEV Community

Vedhashree Sampath
Vedhashree Sampath

Posted on • Originally published at Medium

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

#typescript #relativepathimports #webdev #programming

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';
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

You can do this:

import { ProductService } from '@core/services/ProductService';
Enter fullscreen mode Exit fullscreen mode

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/*"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Local Install (recommended)

Install as a development dependency in your project:

with npm:

npm install --save-dev ts-path-alias-fixer
Enter fullscreen mode Exit fullscreen mode

or with Yarn:

yarn add --dev ts-path-alias-fixer
Enter fullscreen mode Exit fullscreen mode

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/*"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

or

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@services/*": ["services/*"],
      "@models/*": ["models/*"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Run the Fixer

From your project root, run with or without optional cli flags as described below:

npx fix-ts-imports
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

to :

import { ProductService } from '@/core/services/ProductService';
Enter fullscreen mode Exit fullscreen mode

You can do this:

npx fix-ts-imports
Enter fullscreen mode Exit fullscreen mode

or

with optional args as

npx fix-ts-imports --dir ./ --alias @ --base src
Enter fullscreen mode Exit fullscreen mode

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/*"],
      }
...
}
Enter fullscreen mode Exit fullscreen mode

or

{
...,
"baseUrl": "./src",
    "paths": {
      "@/*": ["/*"],
...,
}
Enter fullscreen mode Exit fullscreen mode

🧪 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/*"]
    },
  }
}
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

After running ts-path-alias-fixer:

Run the below from your command line

npx fix-ts-imports --dir ./ --alias @ --base src
Enter fullscreen mode Exit fullscreen mode

and your files will get converted to

import { ApiService } from '@/services/ApiService';
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

and your files will get converted to

import { ApiService } from '@services/ApiService';
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

and your files will get converted to

import { Button} from '@components/buttonComponent';
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Run with custom options:

npx fix-ts-imports --dir ./src --alias @ --base src --dry-run
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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! 👨‍💻👩‍💻

Top comments (0)