@uqt/tspr v0.0.1

@uqt/tspr

CLI tool and runtime API 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.

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 replace referenced projects.

Solution

The package provides both a CLI as well as exposing a runtime API to programmatic rewrite and replace the imports paths of a typescript project (and optionally the 'referenced' projects).

Installation

# Install Globally
npm install -g @uqt/tspr

# Install locally
npm install --save-dev @uqt/tspr

Versioning

The package will follow semver versioning

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.

# Globally
tspr

# Locally
npx tspr

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

# 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

// commonjs
const tspr = require('@uqt/tspr');

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

// es6
import { tsPathReplace } from '@uqt/tspr';

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

API Documentation

CLI Interface

tspr [options]

Programmatically

tsPathReplace([options]);

Options \<Object>

Examples

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

# 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

You should see some logging output 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!

TODO -> Document this

Commit Message Guidelines

https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit

Known limitations

• Will only respect the first element in the paths array.
• The referenced tsConfig in the references must point to an actual project config file, it can't be a config that references other projects and has not src's

TODO

• Tests