resolve-tspaths

resolve-tspaths

If you use Typescript's path mapping feature to avoid ../../../../../ in your imports, you may have found that compiling with tsc doesn't convert your aliases to proper relative paths. This causes problems as the compiled JavaScript code can't actually run with those path aliases - you'll get a "module not found" error. If your project exports type definitions, your .d.ts files will also be broken if they are shipped with path aliases.

Use this package after tsc builds your code to replace any path aliases with relative paths - this means that you can develop using path aliases whilst still being able to ship working JavaScript code.

Yes, there are plugins that can handle this when you use bundlers such as Webpack or Rollup. But if you don't want to use a bundler, this package is a convenient solution.

Sample tsconfig.json:

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

The following types of paths are currently supported:

CommonJS imports

const { ... } = require("~/some/path");

ESM imports

import * as stuff from "~/some/path";
import stuff from "~/some/path";
import { stuff } from "~/some/path";
import { stuff as myStuff } from "~/some/path";

ESM dynamic imports

const stuff = await import("~/some/path");

ESM exports

export * from "~/some/path";
export * as stuff from "~/some/path":
export { stuff } from "~/some/path";
export { stuff as myStuff } from "~/some/path";

CLI Usage

1. Install as a dev dependency using npm or yarn.

   yarn add -D resolve-tspaths
   

   npm install --save-dev resolve-tspaths
   

2. Add it as a part of your build script in package.json after tsc.

   {
     "scripts": {
       "build": "tsc && resolve-tspaths"
     }
   }
   

Programmatic Usage

1. Install as a dev dependency using npm or yarn.

   yarn add -D resolve-tspaths
   

   npm install --save-dev resolve-tspaths
   

2. Import the resolveTsPaths function and call it with the appropriate options.

   import { resolveTsPaths } from "resolve-tspaths";
   

Options

resolve-tspaths uses some reasonable defaults. For most cases, you probably won't need to specify any options.

--project <project>, -p <project>

Specify the tsconfig that the program should use. If not provided, it defaults to tsconfig.json.

--src <path>, -s <path>

Specify the source directory. If not provided, it defaults to ./src.

--out <path>, -o <path>

Specify the output directory of the compiled code where resolve-tspaths should perform its changes. If not provided, it will default to compilerOptions.outDir from your tsconfig.

--ext <extensions>

Provide a comma separated list of file extensions in the output directory that the program should process. Defaults to js,d.ts, which will process .js and .d.ts files.

--verbose

Use this flag to print verbose logs to the console.

This option is only available when using the CLI.

--noEmit

Use this flag to not emit any changes to your files. Recommended to be used with --verbose for debugging which files the program will change if you don't use --noEmit.

This option is only available when using the CLI.

Comparison to existing packages

tsconfig-paths

tsconfig-paths is a runtime dependency. resolve-tspaths is used at build time, which means your shipped code doesn't need to have this package included, and can run natively using Node or in the browser.

tscpaths

Performs the same function as tscpaths - but that project is no longer maintained. A pain point with that package was also that it no control over the logging which was extremely verbose. resolve-tspaths provides several more options for better control, and it's also well tested.

Inspiration

This project was heavily inspired by tscpaths by joonhocho, but it is sadly no longer maintained. My first attempt at building this library was based on a fork of tscpaths. Since the project has matured, it was moved out to its own repository.

Contributors

Thanks goes to these wonderful people (emoji key):

Ben Yap 💻 ⚠️ 📖

Chocobozzz 💻 ⚠️ 🐛

qiaoruntao 💻 ⚠️

Felix Viernickel 🐛 ⚠️ 💻

Kaic Bastidas 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

License

See LICENSE.