tsconfig-alias-converter

Convert relative imports to TypeScript path aliases automatically, based on your tsconfig.json configuration.

Features

• 🎯 Zero configuration - Reads path aliases directly from tsconfig.json
• 🚀 CLI tool - Easy to integrate into your workflow
• 📦 Programmatic API - Use it in your own tools
• 🔒 Type-safe - Full TypeScript support
• 🏗️ Clean architecture - Well-structured and maintainable code

Installation

npm install --save-dev @frantisekstanko/tsconfig-alias-converter

Usage

CLI

Convert imports in specific files:

npx tsconfig-alias-converter src/**/*.ts

Specify a custom tsconfig path:

npx tsconfig-alias-converter src/**/*.ts --tsconfig=./tsconfig.build.json

Programmatic API

import { TsconfigAliasConverter } from '@frantisekstanko/tsconfig-alias-converter'

const result = TsconfigAliasConverter.processFiles(
  ['src/file1.ts', 'src/file2.ts'],
  './tsconfig.json',
)

console.log(`Modified ${result.modifiedCount} of ${result.totalCount} files`)

Advanced Usage

Use individual components for more control:

import {
  TsconfigReader,
  ImportRewriter,
  FileProcessor,
} from '@frantisekstanko/tsconfig-alias-converter'

const aliasConfigs = TsconfigReader.readAliasConfigurations('./tsconfig.json')
const rewriter = new ImportRewriter(aliasConfigs)
const processor = new FileProcessor(rewriter)

const wasModified = processor.processFile('./src/example.ts')

How It Works

Given a tsconfig.json with path aliases:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"],
      "@tests/*": ["tests/*"]
    }
  }
}

The tool will convert relative imports:

import { helper } from '../../../utils/helper.js'
import { config } from '../../config.js'

To alias imports:

import { helper } from '@/utils/helper.js'
import { config } from '@/config.js'

Integration

With package.json scripts

{
  "scripts": {
    "fix-imports": "tsconfig-alias-converter src/**/*.ts tests/**/*.ts"
  }
}

With git hooks (using husky)

npx husky add .husky/pre-commit "npm run fix-imports"

With lint-staged

{
  "lint-staged": {
    "*.ts": ["tsconfig-alias-converter"]
  }
}

API

TsconfigAliasConverter.processFiles(filePaths, tsconfigPath?)

Process multiple files and convert their imports.

• filePaths: Array of file paths to process
• tsconfigPath: Optional path to tsconfig.json (defaults to ./tsconfig.json)
• Returns: { modifiedCount: number, totalCount: number }

TsconfigReader.readAliasConfigurations(tsconfigPath)

Read and parse path alias configurations from tsconfig.json.

• tsconfigPath: Path to tsconfig.json
• Returns: AliasConfiguration[]

ImportRewriter

Rewrite imports in file content.

const rewriter = new ImportRewriter(aliasConfigurations)
const { modified, content } = rewriter.rewriteImportsInFile(
  filePath,
  fileContent,
)

FileProcessor

Process files on disk.

const processor = new FileProcessor(importRewriter)
const wasModified = processor.processFile(filePath)

Requirements

• Node.js >= 20.0.0
• npm >= 10.0.0

License

MIT © Frantisek Stanko