@bleed-believer/path-alias

A package to bind paths alias, resolving the source directory when the app is launched with ts-node, or resolving the out directory when ts-node isn't used. Includes some utilities in case if you need to generate paths dinamically depending of the code that is running. Now you can use this package with proyects transpiled by swc (see details here) and now has monorepo support (see here for details).

With this package, you can forget about those ugly imports like:

import { Jajaja } from '../../../../../../../jajaja.js';
import { Gegege } from '../../../../../gegege.js';

...and instead you can use alias like this (with the power of intellisense):

import { Jajaja } from '@alias-a/jajaja.js';
import { Gegege } from '@alias-b/gegege.js';

About monorepo support

Now this package has monorepo support, thanks for arjunyel colaboration, and for now it's an experimental function. This functionality was tested only with NX monorepo, for that reason please first check this example and test the package functionality in your specific use cases before to implement in production.

Disclaimers

Since ESM hs been heavely adopted by the whole node.js community (including transpilers, unit testing, and many other libraries), from now (from v0.10.17 exactly) the CJS support has been removed. If you still needs the CJS compatibility, considerate these options:

• @bleed-believer/path-alias v0.10.16 or earlier.
• ts-path-mapping (deprecated).

This package is heavely inspired in this response, so I give my gratitude to the charles-hallen work. If you see that the Loader API has been changed and this package stopped working, create an GitHub Issue notifying of the problem.

Also, this package is experimental and probably can generate unexpected behaviors, or performance issues. For that reason, you must test intensively this package in all possible use cases if do you want to implement in production.

Installation

If you don't have installed ts-node, now is the moment:

npm i --save-dev ts-node

...and install this package as a dependency:

npm i --save @bleed-believer/path-alias

Usage

To explain all features of this package, we will use this project estructure as example:

# Your current working directory
project-folder
│   # The project dependencies
├── node_modules
│
│   # The transpiled files
├── dist
│   │   # The file when the app starts
│   ├── index.js
│   │   
│   ├── folder-a
│   │   ├── ...
│   │   └── ...
│   ├── folder-b
│   │   ├── ...
│   │   └── ...
│   └── ...
│
│   # The source code
├── src
│   │   # The file when the app starts
│   ├── index.ts
│   │   
│   ├── folder-a
│   │   ├── ...
│   │   └── ...
│   ├── folder-b
│   │   ├── ...
│   │   └── ...
│   └── ...
│
│   # The project configuration files
├── package.json
├── package-lock.json
└── tsconfig.json

Configure your tsconfig.json

This package reads the tsconfig.json file (and is capable to find values if the file extends another configuration files) to declare the alias. A typical configuration coul be similar to this:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "es2022", /* or "esnext" if you want (not tested yet) */

        "rootDir": "./src",
        "outDir": "./dist",

        "baseUrl": "./src",
        "paths": {
            "@alias-a/*": ["./folder-a/*"],
            "@alias-b/*": ["./folder-b/*"],
        }
    }
}

The fields listed in the example of above are all required in order to the correct working of the package.

• Execute the source code with ts-node:

  node \
  --loader @bleed-believer/path-alias/esm \
  ./src/index.ts

• Execute the transpiled code:

  node \
  --loader @bleed-believer/path-alias/esm \
  ./dist/index.js

Unit testing with ava

Create in your folder where your package.json is located a file called "ava.config.mjs". Assuming that your "rootDir" is "./src", set that file like this:

export default {
    files: [
        './src/**/*.test.ts',
        './src/**/*.test.mts',
    ],
    extensions: {
        ts: 'module',
        mts: 'module',
    },
    nodeArguments: [
        '--loader=@bleed-believer/path-alias/esm',
    ]
}

Utilities

Function isTsNode

If you want to check if ts-node is running, you can execute this function:

import { isTsNode } from '@bleed-believer/path-alias';

const response = isTsNode();  // Returns a boolean
console.log('if ts-node is running?', response); 

Function pathResolve

Resolve any subfolder of "rootDir" depending if ts-node is running. For example, imagine do you want to resolve the path "./src/folder-a/inner/*":

import { pathResolve } from '@bleed-believer/path-alias';

const path = pathResolve('folder-a', 'index.ts');
console.log('path:', path);

With ts-node the output is:

node \
--loader @bleed-believer/path-alias/esm \
./src/folder-a/index.ts

# path: /current/working/directory/src/folder-a/index.ts

With the transpiled code:

node \
--loader @bleed-believer/path-alias/esm \
./dist/folder-a/index.js

# path: /current/working/directory/dist/folder-a/index.js

About SWC

In case you want to execute your project using ts-node, the command is the same:

node \
--loader @bleed-believer/path-alias/esm \
./src/index.ts

However if you need to executed your transpiled project by swc, you don't need to use the loader, just call your root file:

node ./dist/index.js

The function pathResolve works perfectly with swc using the example of above, so you don't need to use the loader in transpiled code to keep the pathResolve function working.

Limitations

• The library requires a "tsconfig.json" file into the current working directory to work. Doesn't matter if that file extends another file, or be a part of a set of inhetirance, while all required properties are accesible through its ancestors.

• The resolve output between "baseURL" and the "paths" declared in the "tsconfig.json" file must always return a path inside of "rootDir" folder.

• swc isn't compatible with alias for a single file, like this: "@data-source": ["./data-source.ts"].