Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@ministryofjustice/module-alias
Advanced tools
@ministryofjustice/module-alias - npm Package Compare versions
Comparing version 1.0.0 to 1.0.1
| { | ||
| "name": "@ministryofjustice/module-alias", | ||
| "description": "Module aliases (based on work by Nick Gavrilov artnikpro@gmail.com)", | ||
| "version": "1.0.0", | ||
| "version": "1.0.1", | ||
| "author": "Form Builder Team <form-builder-team@digital.justice.gov.uk>", | ||
@@ -61,3 +61,5 @@ "contributors": [ | ||
| }, | ||
| "_moduleDirectories": ["test/src/node_modules_custom"], | ||
| "_moduleDirectories": [ | ||
| "test/src/node_modules_custom" | ||
| ], | ||
| "_moduleAliases": { | ||
@@ -64,0 +66,0 @@ "@src": "test/src", |
179
README.md
@@ -1,8 +0,6 @@ | ||
| # module-alias | ||
| [![NPM Version][npm-image]][npm-url] | ||
| [![Build Status][travis-image]][travis-url] | ||
| # @ministryofjustice/module-alias | ||
| Create aliases of directories and register custom module paths in NodeJS like a boss! | ||
| Map package aliases and directories to their location of the file system, with configuration in `package.json`. | ||
| No more shit-coding paths in Node like so: | ||
| Not: | ||
@@ -12,26 +10,14 @@ ```js | ||
| ``` | ||
| Enough of this madness! | ||
| Just create an alias and do it the right way: | ||
| But: | ||
| ```js | ||
| var module = require('@deep/module') | ||
| // Or ES6 | ||
| import module from '@deep/module' | ||
| 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: | ||
| Or you can register _directories_ that will behave like `node_modules`. | ||
| ```js | ||
| require('my_private_module'); | ||
| // Or ES6 | ||
| import module from 'my_private_module' | ||
| ``` | ||
| **WARNING:** This module should not be used in other npm modules since it modifies the default `require` behavior! It is designed to be used for development of final projects i.e. web-sites, applications etc. | ||
| ## Install | ||
| ``` | ||
| npm i --save module-alias | ||
| npm i @ministryofjustice/module-alias | ||
| ``` | ||
@@ -41,146 +27,37 @@ | ||
| Add your custom configuration to your `package.json` (in your application's root) | ||
| Add configuration to `package.json`: | ||
| ### Aliases | ||
| ```js | ||
| // Aliases | ||
| "_moduleAliases": { | ||
| "@root" : ".", // Application's root | ||
| "@deep" : "src/some/very/deep/directory/or/file", | ||
| "@my_module" : "lib/some-file.js", | ||
| "something" : "src/foo", // Or without @. Actually, it could be any string | ||
| { | ||
| "_moduleAliases": { | ||
| "@root" : ".", // Application's root | ||
| "@deep" : "src/some/very/deep/directory/or/file", | ||
| "@my_module" : "lib/some-file.js", | ||
| "something" : "src/foo" | ||
| } | ||
| } | ||
| // Custom module directories, just like `node_modules` but with your private modules (optional) | ||
| "_moduleDirectories": ["node_modules_custom"], | ||
| ``` | ||
| Then add this line at the very main file of your app, before any code | ||
| ### Directories | ||
| ```js | ||
| require('module-alias/register') | ||
| ``` | ||
| { | ||
| "_moduleDirectories": [ | ||
| "src/node_modules_custom" | ||
| ] | ||
| } | ||
| **And you're all set!** Now you can do stuff like: | ||
| ```js | ||
| require('something') | ||
| const module = require('@root/some-module') | ||
| const veryDeepModule = require('@deep/my-module') | ||
| const customModule = require('my_private_module') // module from `node_modules_custom` directory | ||
| // Or ES6 | ||
| import 'something' | ||
| import module from '@root/some-module' | ||
| import veryDeepModule from '@deep/my-module' | ||
| import customModule from 'my_private_module' // module from `node_modules_custom` directory | ||
| ``` | ||
| ## Advanced usage | ||
| Then include this line at the top of your module: | ||
| 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() | ||
| require('module-alias/register') | ||
| ``` | ||
| ## Usage with WebPack | ||
| `@ministryofjustice/module-alias` will resolve the location of `package.json` and register any aliases contained in it before applying the alias to any `require` calls made by your module. | ||
| 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! | ||
| ## About this package | ||
| ```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). | ||
| ## 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). | ||
| ## How it works? | ||
| In order to register an alias it modifies the internal `Module._resolveFilename` method so that when you use `require` or `import` it first checks whether the given string starts with one of the registered aliases, if so, it replaces the alias in the string with the target path of the alias. | ||
| In order to register a custom modules path (`addPath`) it modifies the internal `Module._nodeModulePaths` method so that the given directory then acts like it's the `node_modules` directory. | ||
| [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 | ||
| ## 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. | ||
| `@ministryofjustice/module-alias` is a fork of [`module-alias`](https://www.npmjs.com/package/module-alias) with an improved mechanism for resolving the location of `package.json` and the removal of some features we do not use (such as custom handlers). |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Worsened metrics
- Total package byte prevSize
- decreased by-33.55%
10198
- Number of lines in readme file
- decreased by-66.49%
62
No dependency changes