@tochii/tsconfig-aliases/README.md

Generate path aliases designed for monorepos and structured projects

# @tochii/tsconfig-aliases

Generate path aliases designed for monorepos and structured projects. It scans your workspace for package folders and auto-generates a valid `compilerOptions.paths` map with configurable output, prefixing, backup support, and more.

- Ideal for monorepos using `packages/*`, `libs/*`, etc.
- Compatible with TypeScript’s `extends` system for sharing config.
- Doesn't modify your root `tsconfig.json` unless you point `out` to it.

**Note:** this package is not a CLI. Go to [CLI version](#cli-version) to use the CLI.

## Table of Contents
- [@tochii/tsconfig-aliases](#tochiitsconfig-aliases)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
      - [CLI version](#cli-version)
  - [Usage](#usage)
    - [Return Value](#return-value)
  - [Options](#options)
  - [Output](#output)
  - [How It Works](#how-it-works)
  - [Backup](#backup)

## Installation
```bash
npm install @tochii/tsconfig-aliases
```

#### CLI version
```bash
npx @tochii/cli generate tsconfig-aliases
```

or install the CLI locally and then run it:
```bash
npm i -D @tochii/cli
```
```bash
tochi generate tsconfig-aliases
```

## Usage
```ts
import tsconfigAliases from '@tochii/tsconfig-aliases';

const result = tsconfigAliases({
    root: process.cwd(),
    dir: ['packages', 'libs'],
    prefix: '@/',
    suffix: '/*',
    match: ['package.json'],
    out: 'tsconfig.aliases.json',
    verbose: 'info',
});
```

### Return Value
Returns an object like:

```ts
{
  outFile: 'tsconfig.aliases.json',
  outDir: '/absolute/path/to/output/dir',
  fullPath: '/absolute/path/to/tsconfig.aliases.json',
  backupDir: '/absolute/path/to/.tsconfig.aliases.backup',
  newPaths: string[],
  oldPaths?: Record<string, string[]>
}
```

## Options

| Option       | Type       | Default                               | Description                                         |
| ------------ | ---------- | ------------------------------------- | --------------------------------------------------- |
| `match`      | `string[]` | `['package.json', 'tsconfig.*.json']` | Globs that identify valid package dirs              |
| `loose`      | `boolean`  | `true`                                | If true, overwrite both alias and non-prefixed keys |
| `prefix`     | `string`   | `'@/'`                                | Prefix for alias names                              |
| `suffix`     | `string`   | `'/*'`                                | Suffix for alias paths                              |
| `root`       | `string`   | `process.cwd()`                       | Root directory to resolve everything from           |
| `dir`        | `string[]` | `['.']`                               | Directories to scan for packages                    |
| `skip`       | `string[]` | `['node_modules']`                    | Directories to skip                                 |
| `out`        | `string`   | `'tsconfig.aliases.json'`             | Path to the generated output file                   |
| `maxBackups` | `number`   | `5`                                   | Maximum number of backups to retain                 |
| `backupDir`  | `string`   | `'.tsconfig.aliases.backup'`          | Path to the backup directory                        |
| `packages`   | `string[]` | `['packages']`                        | Known monorepo package folder names                 |
| `verbose`    | `'fatal'   | 'error'                               | 'warn'                                              | 'info' | 'debug' | 'trace' | 'off'` | `'trace'` | Logging level |

## Output

- A `tsconfig.aliases.json` file containing `compilerOptions.paths`.
- Logs with summary of new and old paths.
- Backups of previous alias configs (see below).

## How It Works

- Recursively scans target directories (`dir`) for folders containing `match` files like `package.json`.
- Sanitizes paths based on the `packages` list and adds them to the alias map.
- Supports prefix/suffix customization (e.g. `@/mypackage/*`).
- Writes a clean `tsconfig.aliases.json`, or merges with an existing one.
- Automatically removes duplicate entries and supports overwrite logic via `loose`.

## Backup

- Each time an alias config is generated, the previous one is backed up with a timestamp:
  ```
  tsconfig.aliases.1718112954678.old.json
  ```
- The backups are stored in `.tsconfig.aliases.backup` (default), or a custom `backupDir`.
- After exceeding `maxBackups`, oldest files are removed.