# @uqt/ts-path-replace

> CLI Tool to replace TypeScript "@alias" paths to relative paths

Latest version **1.1.1** (published 2021-01-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @uqt/ts-path-replace
pnpm add @uqt/ts-path-replace
yarn add @uqt/ts-path-replace
bun add @uqt/ts-path-replace
```

Provides the command `tspr`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2021-01-03 |
| First published | 2019-10-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 31.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Jonathon Adams |
| Maintainers | uqt |
| Keywords | cli, TypeScript, path, replace, alias, rewrite |

## Links

- npm: https://www.npmjs.com/package/@uqt/ts-path-replace
- Repository: https://github.com/jonathonadams/ts-path-replace
- Homepage: https://github.com/jonathonadams/ts-path-replace#readme
- Issues: https://github.com/jonathonadams/ts-path-replace/issues
- npm.io page: https://npm.io/package/@uqt/ts-path-replace

## Dependencies (4)

- [minimist](https://npm.io/package/minimist.md) ^1.2.5
- [node-watch](https://npm.io/package/node-watch.md) ^0.7.1
- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.2
- [replace-in-file](https://npm.io/package/replace-in-file.md) ^6.1.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 1.1.1 (latest) — 2021-01-03
- 1.1.0 — 2020-11-19
- 1.0.3 — 2020-11-17
- 1.0.2 — 2020-07-22
- 1.0.1 — 2020-07-20
- 1.0.0 — 2020-07-19
- 0.0.5 — 2019-10-20
- 0.0.4 — 2019-10-20
- 0.0.3 — 2019-10-13
- 0.0.2 — 2019-10-10

## README

# @uqt/ts-path-replace

CLI tool to replace TypeScript paths from `@alias/import/paths` to `../relative/import/paths`

## Why this package

The long standing issues with TS not outputting relative paths can be found [here](https://github.com/Microsoft/TypeScript/issues/10866).

While there are a number of packages that have already tackled this issues, for whatever reason they were either limiting or did not suite my needs, hence this project.

Additionally, as of TSv3.0, external projects can be referenced in the `references` property of the tsconfig.json. This allows your project to `reference` and consume
code that is not under the source directory of the current project. At the time of creating the package, no other solution that I could get to work also replaces referenced projects.

## Solution

The package provides a CLI and runtime API to rewrite and replace the imports paths of a typescript project. Additionally it will also replace any referenced projects.

## Versioning

The package follows [semver](https://semver.org/) versioning and releases are automated by [semantic release](https://www.npmjs.com/package/semantic-release)

## Installation

```bash
# Install Globally
npm install -g @uqt/ts-path-replace

# Install locally
npm install --save-dev @uqt/ts-path-replacr
```

## Usage

### CLI

To use the CLI, navigate to the directory and run `tspr`. By default, it will read the `tsconfig.json` located in the root directory.

```bash
# Globally
$ tspr

# Locally
$ npx tspr
```

Optionally, you can pass the path to the desired `tsconfig.json` to process

```bash
# Passing in a path to a tsconfig.json
$ npx tspr --tsConfig some/path/to/tsconfig.json

# Replace the paths for the references projects and watch the output directories for changes to rerun
$ npx tspr --tsConfig path/to/tsconfig.json --references true --watch true
```

### Runtime

```js
// commonjs
const tspr = require('@uqt/ts-path-replace');

tspr.tsPathReplace({ path: 'path/to/tsconfig.json' });

// ES6
import { tsPathReplace } from '@uqt/ts-path-replace';

tsPathReplace({
  path: 'path/to/tsconfig.json',
  references: true,
  watch: true,
});
```

## API Documentation

```bash
# CLI
tspr [--option]
```

```JavaScript
// run time
tsPathReplace([options]);
```

**Options** \<Object\>

| Option                  | Description                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| tsConfig: **string**    | Path to the json config file to process **Default:** `tsconfig.json`                         |
| references: **boolean** | Also replace imports in any referenced projects **Default:** `false`                         |
| watch / w: **boolean**  | Watch the output directory for file changes and re-run the path replace **Default:** `false` |
| ext **string**          | Append a file extension to the paths. **Default:** no extension added                        |

**Returns** Promise\<Object>

| Property                   | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| running: **boolean**       | If the process is still running (watch mode)                      |
| stop(): **Promise\<void>** | A method to stop the process if it currently running (watch mode) |

## Example

There is an example of a 'monorepo' style setup located in the /example directory.

The examples includes multiple 'apps' with multiple referenced projects.

To run the example

```bash
# You will have to build the project first
npm run build
# Build the example
npm run example:build
# run the path replacement
npm run example:tspr
# run the project
npm run example:run
```

Running the above should should build the example, replace the import paths and then output some logging to the terminal.

If you look in the `example/out` directory, you should see all `.js` files have been replaced with relative imports

## Contributing

Contributions and PR's are welcome!

### Commit Message Guidelines

[Commit Guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit)

## Known limitations

- Only the first element of each of the paths properties is used.
- The referenced tsConfig in the references must point to an project config file with source files and an output directory, it can't be a config that references other projects and has not project files.

---
_Source: https://npm.io/package/@uqt/ts-path-replace · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._