What is app-module-path?
The app-module-path npm package allows you to add directories to the Node.js module search path, making it easier to require modules without using relative paths.
What are app-module-path's main functionalities?
Add a single directory to the module search path
This feature allows you to add a single directory to the module search path. In this example, the 'lib' directory is added, making it possible to require modules from 'lib' without using relative paths.
const path = require('path');
require('app-module-path').addPath(path.join(__dirname, 'lib'));
Add multiple directories to the module search path
This feature allows you to add multiple directories to the module search path. In this example, both 'lib1' and 'lib2' directories are added, making it possible to require modules from either directory without using relative paths.
const path = require('path');
const appModulePath = require('app-module-path');
appModulePath.addPath(path.join(__dirname, 'lib1'));
appModulePath.addPath(path.join(__dirname, 'lib2'));
Add a directory to the module search path using environment variables
This feature allows you to add a directory to the module search path using environment variables. In this example, the 'lib' directory is added to NODE_PATH, and the module paths are re-initialized to include this directory.
process.env.NODE_PATH = path.join(__dirname, 'lib');
require('module').Module._initPaths();
Other packages similar to app-module-path
module-alias
The module-alias package allows you to create custom module aliases and register directories for module resolution. It provides similar functionality to app-module-path but also includes the ability to create aliases for specific modules.
require-alias
The require-alias package allows you to define aliases for module paths, making it easier to require modules without using relative paths. It is similar to app-module-path but focuses more on aliasing specific module paths rather than adding directories to the search path.
rechoir
The rechoir package allows you to register require hooks for different file types, enabling you to require modules with non-standard extensions. While it provides some overlapping functionality with app-module-path, it is more focused on handling different file types rather than modifying the module search path.
app-module-path
This simple module enables you to add additional directories to the Node.js module search path (for top-level app modules only). This allows application-level modules to be required as if they were installed into the node_modules
directory.
Installation
npm install app-module-path --save
Usage
require('app-module-path').addPath(baseDir);
IMPORTANT:
The search path should be modified before any modules are loaded!
Example:
In your my-app/index.js
(or my-app/server.js
) file:
require('app-module-path').addPath(__dirname);
Given the following example directory structure:
- my-app/
- src/ - Source code and application modules directory
- foo/ - A module directory
- bar/ - Another module directory
- node_modules/ - Installed modules
- installed-baz/ - An installed module
- index.js - Main script
The following will work for any modules under the src
directory:
var foo = require('src/foo');
var bar = require('src/bar');
var baz = require('installed-baz');
Lastly, by design, installed modules (i.e. modules under the node_modules
directory) will not be able to require application-level modules so the following will not work:
var foo = require('src/foo');
var bar = require('src/bar');
Alternate Usage (app-module-path/register
)
This module supports an alternate method of adding a path to the Node.js module search path that requires less code. Requiring or importing the app-module-path/register
module will result in the directory of the calling module being added to the Node.js module search path as shown below:
Explicitly enabling a directory/package
By default, app-module-path
will not attempt to resolve app modules from a directory that is found to be within a node_modules
directory. This behavior can be changed by explicitly enabling app-module-path
to work for descendent modules of a specific directory. For example:
var packageDir = path.dirname(require.resolve('installed-module-allowed'));
require('../').enableForDir(packageDir);
ES5
require('app-module-path/register');
require('app-module-path').addPath(__dirname);
ES6
import "app-module-path/register";
import { addPath } from 'app-module-path';
addPath(__dirname);
Alternative Usage (app-module-path/cwd
)
Additionally, requiring or importing app-module-path/cwd
will result in the current working directory of the Node.js process being added to the module search path as shown below:
ES5
require('app-module-path/cwd');
require('app-module-path').addPath(process.cwd());
ES6
import "app-module-path/cwd";
import { addPath } from 'app-module-path';
addPath(process.cwd());
Additional Notes
-
Search path order:
- App module paths will be added to the end of the default module search path. That is, if a module with the same name exists in both a
node_modules
directory and an application module directory then the module in the node_modules
directory will be loaded since it is found first.
This behavior is new in v2.x. In v1.x, this search order was reversed
-
Node.js compatibility:
- This module depends on overriding/wrapping a built-in Node.js method, and it is possible (but unlikely) that this behavior could be broken in a future release of Node.js (at which point a workaround would need to be used)
- This module will not change or break modules installed into the
node_modules
directory.
-
Recommendations:
- Since this module changes the Node.js convention of how non-relative modules are resolved, it is recommended (but not required) to put all app modules in a common directory below the application root (such as
my-app/src
or my-app/app_modules
) and then to add the application root to the search path. The require calls would then be something like require('src/foo')
or require('app_modules/foo')
. The common prefix makes it more clear that the module can be found in the application's modules directory and not in the node_modules
directory.
Contribute
Pull requests, bug reports and feature requests welcome.
License
BSD-2-Clause