1

node_modules/module-alias/README.md

@@ -0,0 +1,246 @@
+# module-alias
+
+[![NPM Version][npm-image]][npm-url]
+
+Donations are much appreciated and would help me continue working on this package! [Donate here ❤️](https://tinyurl.com/donate-module-alias).
+
+---
+
+Create aliases of directories and register custom module paths in NodeJS like a boss!
+
+No more long paths in Node, like:
+
+```js
+import something from ('../../../../some/very/deep/module');
+```
+
+Enough of this madness!
+
+Just create an alias and do it the right way:
+
+```js
+import module from '@deep/module'
+// Or CommonJS
+const module = require('@deep/module')
+```
+
+It also allows you to register directories that will act just like `node_modules` but with your own private modules, so that you can access them directly:
+
+```js
+import module from 'my_private_module'
+// Or CommonJS
+const module = require('my_private_module')
+```
+
+**WARNING:** If you are going to use this package within another NPM package, please read [Using within another NPM package](#using-within-another-npm-package) first to be aware of potential caveats.
+
+## Install
+
+```
+npm i --save module-alias
+```
+
+## Usage
+
+### ES Modules (Node 18.19+)
+
+Add your custom configuration to your `package.json` (in your application's root):
+
+```json
+{
+  "_moduleAliases": {
+    "@root": ".",
+    "@lib": "src/lib",
+    "@utils": "src/utils"
+  },
+  "_moduleDirectories": ["node_modules_custom"]
+}
+```
+
+Run your app with the `--import` flag:
+
+```bash
+node --import module-alias/register ./app.mjs # Or use a custom registerer, see below
+```
+
+**Why the `--import` flag?**
+
+Unlike CommonJS, you cannot import `module-alias/register` at runtime. All `import` statements are hoisted and resolved before any code runs. The `--import` flag loads the loader hooks before your application starts.
+
+### Programmatic ESM Usage (Node 22.15+):
+
+For programmatic alias registration, create a custom loader file:
+
+```js
+// my-aliases.mjs
+import { addAlias, addAliases } from 'module-alias'
+
+addAlias('@utils', process.cwd() + '/src/utils')
+// or
+addAliases({
+  '@utils': process.cwd() + '/src/utils',
+  '@lib': process.cwd() + '/src/lib'
+})
+
+// Custom handler function
+addAlias('@src', (fromPath, request, alias) => {
+  // fromPath - Full path of the file from which `import` was called
+  // request - The path that was passed into `import` (e.g. '@src/utils.js')
+  // alias - The alias being matched (`@src` in this case)
+  const subpath = request.slice(alias.length) // e.g. '/utils.js'
+  const base = fromPath.includes('/tests/') ? '/mocks' : '/src'
+  return process.cwd() + base + subpath
+})
+```
+
+Then use it with the `--import` flag:
+
+```bash
+node --import ./my-aliases.mjs ./app.mjs
+```
+
+### CommonJS (older Node 12+ versions)
+
+Add your custom configuration to your `package.json`:
+
+```json
+{
+  "_moduleAliases": {
+    "@root": ".",
+    "@deep": "src/some/very/deep/directory/or/file",
+    "@my_module": "lib/some-file.js"
+  },
+  "_moduleDirectories": ["node_modules_custom"]
+}
+```
+
+Then add this line at the very main file of your app, before any code:
+
+```js
+require('module-alias/register')
+```
+
+Now you can use aliases:
+
+```js
+require('something')
+const module = require('@root/some-module')
+const veryDeepModule = require('@deep/my-module')
+```
+
+## Programmatic CommonJS usage
+
+If you don't want to modify your `package.json` or you just prefer to set it all up programmatically, then the following methods are available for you:
+
+* `addAlias('alias', 'target_path')` - register a single alias
+* `addAliases({ 'alias': 'target_path', ... }) ` - register multiple aliases
+* `addPath(path)` - Register custom modules directory (like node_modules, but with your own modules)
+
+_Examples:_
+```js
+const moduleAlias = require('module-alias')
+
+//
+// Register alias
+//
+moduleAlias.addAlias('@client', __dirname + '/src/client')
+
+// Or multiple aliases
+moduleAlias.addAliases({
+  '@root'  : __dirname,
+  '@client': __dirname + '/src/client',
+  ...
+})
+
+// Custom handler function (starting from v2.1)
+moduleAlias.addAlias('@src', (fromPath, request, alias) => {
+  // fromPath - Full path of the file from which `require` was called
+  // request - The path (first argument) that was passed into `require`
+  // alias - The same alias that was passed as first argument to `addAlias` (`@src` in this case)
+
+  // Return any custom target path for the `@src` alias depending on arguments
+  if (fromPath.startsWith(__dirname + '/others')) return __dirname + '/others'
+  return __dirname + '/src'
+})
+
+//
+// Register custom modules directory
+//
+moduleAlias.addPath(__dirname + '/node_modules_custom')
+moduleAlias.addPath(__dirname + '/src')
+
+//
+// Import settings from a specific package.json
+//
+moduleAlias(__dirname + '/package.json')
+
+// Or let module-alias to figure where your package.json is
+// located. By default it will look in the same directory
+// where you have your node_modules (application's root)
+moduleAlias()
+```
+
+## Usage with Webpack
+
+Luckily, WebPack has a built in support for aliases and custom modules directories so it's easy to make it work on the client side as well!
+
+```js
+// webpack.config.js
+const npm_package = require('./package.json')
+
+module.exports = {
+  entry: { ... },
+  resolve: {
+    root: __dirname,
+    alias: npm_package._moduleAliases || {},
+    modules: npm_package._moduleDirectories || [] // eg: ["node_modules", "node_modules_custom", "src"]
+  }
+}
+```
+
+More details on the [official documentation](https://webpack.js.org/configuration/resolve).
+
+## Usage with Jest
+
+Unfortunately, `module-alias` itself would not work from Jest due to a custom behavior of Jest's `require`. But you can use it's own aliasing mechanism instead. The configuration can be defined either in `package.json` or `jest.config.js`. The example below is for `package.json`:
+
+```js
+"jest": {
+  "moduleNameMapper": {
+    "@root/(.*)": "<rootDir>/$1",
+    "@client/(.*)": "<rootDir>/src/client/$1"
+  },
+}
+```
+
+More details on the [official documentation](https://jestjs.io/docs/en/configuration#modulenamemapper-objectstring-string--arraystring).
+
+## Using within another NPM package
+
+You can use `module-alias` within another NPM package, however there are a few things to take into consideration.
+
+1. As the aliases are global, you should make sure your aliases are unique, to avoid conflicts with end-user code, or with other libraries using module-alias. For example, you could prefix your aliases with '@my-lib/', and then use require('@my-lib/deep').
+2. The internal "register" mechanism may not work, you should not rely on `require('module-alias/register')` for automatic detection of `package.json` location (where you defined your aliases), as it tries to find package.json in either the current working directory of your node process, or two levels down from node_modules/module-alias. It is extremely likely that this is end-user code. So, instead, your should either register aliases manually with `moduleAlias.addAlias`, or using something like `require('module-alias')(__dirname)`.
+
+Here is an [example project](https://github.com/Kehrlann/module-alias-library).
+
+## Known incompatibilities
+
+This module does not play well with:
+
+- Front-end JavaScript code. Module-alias is designed for server side so do not expect it to work with front-end frameworks (React, Vue, ...) as they tend to use Webpack. Use Webpack's [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) mechanism instead.
+- [Jest](https://jestjs.io), which discards node's module system entirely to use it's own module system, bypassing module-alias.
+- The [NCC compiler](https://github.com/zeit/ncc), as it uses WebPack under the hood without exposing properties, such as resolve.alias. It is not [something they wish to do](https://github.com/zeit/ncc/pull/460).
+
+## Refactor your code (for already existing projects)
+
+If you are using this on an existing project, you can use [relative-to-alias](https://github.com/s-yadav/relative-to-alias) to refactor your code to start using aliases.
+
+## Special Thanks
+
+Special thanks to [Artur Havrylov](https://github.com/artnikbrothers) and [Daniel Garnier-Moiroux](https://www.npmjs.com/~kehrlann) for valuable contributions.
+
+[npm-image]: https://img.shields.io/npm/v/module-alias.svg
+[npm-url]: https://npmjs.org/package/module-alias
+[travis-image]: https://img.shields.io/travis/ilearnio/module-alias/master.svg
+[travis-url]: https://travis-ci.org/ilearnio/module-alias