tessl/npm-app-module-path

Simple module to add additional directories to the Node module search for top-level app modules

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

App Module Path

Name: tessl/npm-app-module-path
Author: tessl

App Module Path is a simple Node.js utility that enables adding additional directories to the Node.js module search path for top-level application modules. This allows application-level modules to be required as if they were installed into the node_modules directory, while maintaining proper isolation to prevent installed modules from accessing application code.

Package Information

Package Name: app-module-path
Package Type: npm
Language: JavaScript
Installation: npm install app-module-path --save

Core Imports

const { addPath, removePath, enableForDir } = require('app-module-path');

For automatic path registration:

// Auto-registers the directory containing the requiring module
require('app-module-path/register');

// Auto-registers the current working directory  
require('app-module-path/cwd');

ES6 imports:

import { addPath, removePath, enableForDir } from 'app-module-path';

// Auto-registration patterns
import 'app-module-path/register';
import 'app-module-path/cwd';

Basic Usage

// IMPORTANT: Add this to the very beginning of your main script
require('app-module-path').addPath(__dirname);

// Now you can require modules from your application directory structure
// as if they were installed in node_modules
const myModule = require('src/my-module');
const anotherModule = require('lib/utils/helper');

Alternative automatic registration:

// Automatically adds the directory containing this file to the search path
require('app-module-path/register');

// Or automatically adds the current working directory
require('app-module-path/cwd');

Architecture

App Module Path works by overriding Node.js's built-in Module._nodeModulePaths method to extend the module resolution system:

Path Management: Maintains an internal list of additional search paths that are appended to Node's default module resolution
Security Model: Only allows application-level modules to access the extended paths; installed modules in node_modules are restricted from accessing application code
Hierarchy Support: Automatically updates parent module paths when new search paths are added
Explicit Enablement: Provides mechanism to explicitly allow specific directories within node_modules to use extended paths

Capabilities

Path Management

Add and remove directories from the Node.js module search path.

/**
 * Adds a directory path to the Node module search path
 * @param {string} path - The directory path to add to the module search path
 * @param {Module} [parent] - The parent module context (defaults to module.parent)
 */
function addPath(path, parent);

/**
 * Removes a directory path from the Node module search path
 * @param {string} path - The directory path to remove from the module search path
 */
function removePath(path);

Usage Examples:

const { addPath, removePath } = require('app-module-path');
const path = require('path');

// Add application source directory to module path  
addPath(path.join(__dirname, 'src'));

// Add multiple directories
addPath(path.join(__dirname, 'lib'));
addPath(path.join(__dirname, 'app'));

// Remove a path when no longer needed
removePath(path.join(__dirname, 'src'));

Directory Enablement

Explicitly enable app-module-path functionality for specific directories, including those within node_modules.

/**
 * Explicitly enables app-module-path functionality for a specific directory
 * @param {string} dir - The directory path to enable for app-module-path resolution
 */
function enableForDir(dir);

Usage Example:

const { enableForDir } = require('app-module-path');
const path = require('path');

// Allow a specific installed package to access application modules
const packageDir = path.dirname(require.resolve('some-installed-package'));
enableForDir(packageDir);

Automatic Registration

Convenience entry points that automatically register paths without explicit function calls.

register.js Entry Point:

// Automatically calls addPath(dirname(module.parent.filename), module.parent)
require('app-module-path/register');

Equivalent to:

const { addPath } = require('app-module-path');
const path = require('path');
addPath(path.dirname(__filename));

cwd.js Entry Point:

// Automatically calls addPath(process.cwd())
require('app-module-path/cwd');

Equivalent to:

const { addPath } = require('app-module-path');
addPath(process.cwd());

Usage Examples:

// At the top of your main application file
require('app-module-path/register');

// Now you can require modules relative to your application root
const utils = require('src/utils');
const config = require('config/settings');

// For projects where modules should be resolved from the CWD
require('app-module-path/cwd');

const appModule = require('app/main-module');

Important Notes

Timing: The search path must be modified before any modules are loaded that depend on the extended paths
Search Order: App module paths are added to the end of the default module search path, so installed modules in node_modules take precedence
Security: By design, modules installed in node_modules cannot access application-level modules unless explicitly enabled via enableForDir
Compatibility: This module overrides a built-in Node.js method and could potentially be affected by future Node.js changes
Cleanup: Both register.js and cwd.js remove themselves from the require cache to ensure the parent module stays up-to-date

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:npm/app-module-path@2.2.x
Publish Source: CLI
Badge