npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@zebreus/resolve-tspaths

v0.8.10

Published

Transform path mappings in your compiled Typescript code

Downloads

31

Readme

resolve-tspaths

npm license

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

  1. 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
  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, along with Typescript 3.x or later.

    yarn add -D resolve-tspaths typescript
    npm install --save-dev resolve-tspaths typescript
  2. 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.