@zebreus/resolve-tspaths
v0.8.10
Published
Transform path mappings in your compiled Typescript code
Downloads
31
Maintainers
Readme
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.
This package also provides a nodejs module loader.
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.js";
import { stuff as myStuff } from "~/some/path.mjs";
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.js";
export { stuff as myStuff } from "~/some/path.mjs";
Node.JS require.resolve
const path = require.resolve("~/some/path");
CLI Usage
Install as a dev dependency using npm or yarn, along with Typescript 3.x or later.
yarn add -D resolve-tspaths typescript
npm install --save-dev resolve-tspaths typescript
Add it as a part of your build script in
package.json
aftertsc
.{ "scripts": { "build": "tsc && resolve-tspaths" } }
Programmatic Usage
Install as a dev dependency using npm or yarn, along with Typescript 3.x or later.
yarn add -D resolve-tspaths typescript
npm install --save-dev resolve-tspaths typescript
Import the
resolveTsPaths
function and call it with the appropriate options.import { resolveTsPaths } from "resolve-tspaths";
Usage as a NodeJS resolver
You can use this with ts-node
and node
to load modules using TypeScript path
aliases at runtime. This feature is still experimental. To specify your tsconfig
file, set the TS_NODE_PROJECT
environment variable.
With ES modules (type: "module")
node --loader ts-node/esm --loader resolve-tspaths/esm src/index.ts
You need a nodejs version which supports ES module loader chaining (at least
16.17.0
or 18.9.0
).
With commonjs modules
ts-node -r resolve-tspaths/cjs src/index.ts
With jest and ES modules
To use resolve-tspaths with jest you need to add it as a transformer in your
jest config. This also automatically enables ts-jest
as a transformer, if you
have that installed. If you want to import ESM-only packages you should also
activate the node --experimental-vm-modules
flag (e.g.
NODE_OPTIONS='--experimental-vm-modules' jest
).
{
"extensionsToTreatAsEsm": [".ts"],
"transform": {
"^.+.m?tsx?$": "resolve-tspaths/jest"
}
}
For commonjs, don't set extensionsToTreatAsEsm
.
You can also configure the typescript transformer (ts-jest
by default) and
select the tsconfig. Default values are:
{
"transform": {
"^.+.m?tsx?$": [
"resolve-tspaths/jest",
{
"tsconfig": "tsconfig.json", // Where to load the tsconfig from
"tsJest": "ts-jest", // The path to ts-jest (or another transformer). Set to an empty string, if you don't want to use another transformer
"tsJestConfig": {} // Config for the other transformer
}
]
}
}
Options
resolve-tspaths
uses some reasonable defaults. For most cases, you probably
won't need to specify any options.
--project <path>, -p <path>
Specify the path to the tsconfig file that the program should use. Defaults to "tsconfig.json" if not provided.
--src <path>, -s <path>
Specify the source directory. Defaults to compilerOptions.rootDir
from your
tsconfig if not provided. If rootDir
is not defined in your tsconfig, it will
default to "src".
--out <path>, -o <path>
Specify the output directory of the compiled code where resolve-tspaths
should
perform its changes. Defaults to compilerOptions.outDir
from your tsconfig if
not provided.
--ext <extension...>
Provide a space-delimited list of file extensions in the output directory that the program should process. Defaults to the following extensions:
js
mjs
cjs
d.ts
d.mts
d.cts
--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):
This project follows the all-contributors specification. Contributions of any kind welcome! Please follow the contributing guidelines.
License
See LICENSE.