CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-require-directory

Recursively iterates over specified directory, require()'ing each file, and returning a nested hash structure containing those modules.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

require-directory

Recursively iterates over specified directory, require()ing each file, and returning a nested hash structure containing those modules. Enables automatic loading and organizing of multiple modules from a directory hierarchy without manually requiring each file.

Package Information

  • Package Name: require-directory
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install require-directory

Core Imports

const requireDirectory = require('require-directory');

Basic Usage

const requireDirectory = require('require-directory');

// Require all files from current directory
const modules = requireDirectory(module);

// Require all files from a specific directory
const routes = requireDirectory(module, './routes');

// With options - only JavaScript files, no recursion
const controllers = requireDirectory(module, './controllers', {
  extensions: ['js'],
  recurse: false
});

Capabilities

Directory Requiring

Recursively processes a directory structure, requiring each file and building a nested hash structure that mirrors the directory layout.

/**
 * Recursively requires all files in a directory and returns nested hash structure
 * @param {Object} module - The module object (typically 'module')
 * @param {string} [path] - Path to directory (defaults to module's directory)
 * @param {Object} [options] - Configuration options
 * @returns {Object} Nested hash structure containing required modules
 */
function requireDirectory(module, path, options);

Parameters:

  • module (required): The module object, typically pass module
  • path (optional): String path to directory to require from. If omitted, uses the directory containing the calling module
  • options (optional): Configuration object for controlling behavior

Returns: Object containing nested hash structure where:

  • File modules are keyed by filename (without extension)
  • Directory modules are keyed by directory name
  • Structure mirrors the filesystem hierarchy

Configuration Options

Control file processing, filtering, and transformation behavior.

interface RequireDirectoryOptions {
  /** Array of file extensions to process */
  extensions?: string[];
  /** Whether to recursively process subdirectories */
  recurse?: boolean;
  /** Function to transform object keys */
  rename?: (name: string, joined: string, filename: string) => string;
  /** Function to transform loaded modules - return value used if truthy, otherwise original object */
  visit?: (obj: any, joined: string, filename: string) => any;
  /** RegExp or function to whitelist files */
  include?: RegExp | ((path: string, filename: string) => boolean);
  /** RegExp or function to blacklist files */
  exclude?: RegExp | ((path: string, filename: string) => boolean);
}

Option Details:

  • extensions: Array of file extensions to include (default: ['js', 'json', 'coffee'])
  • recurse: Boolean controlling recursive directory processing (default: true)
  • rename: Function to transform object keys, receives (name, joined, filename)
  • visit: Function to transform loaded modules, receives (obj, joined, filename). Return value is used if truthy, otherwise original object is kept
  • include: RegExp or function to whitelist specific files
  • exclude: RegExp or function to blacklist specific files

Usage Examples:

// Custom extensions
const modules = requireDirectory(module, './lib', {
  extensions: ['js', 'ts']
});

// No recursion
const topLevel = requireDirectory(module, './routes', {
  recurse: false
});

// File filtering with RegExp
const jsOnly = requireDirectory(module, './src', {
  include: /\.js$/
});

// File filtering with function
const filtered = requireDirectory(module, './controllers', {
  exclude: (path, filename) => filename.startsWith('test')
});

// Key transformation
const uppercased = requireDirectory(module, './models', {
  rename: (name) => name.toUpperCase()
});

// Module transformation
const wrapped = requireDirectory(module, './middleware', {
  visit: (obj) => {
    // Wrap functions with logging
    if (typeof obj === 'function') {
      return (...args) => {
        console.log('Calling:', obj.name);
        return obj(...args);
      };
    }
    return obj;
  }
});

Default Options Access

Access the default configuration object used by requireDirectory.

/**
 * Default options object used by requireDirectory
 */
const defaults: RequireDirectoryOptions;

The defaults object contains:

const defaults = {
  extensions: ['js', 'json', 'coffee'],
  recurse: true,
  rename: function(name) { return name; },
  visit: function(obj) { return obj; }
};

Usage:

// Access default options
const defaultOpts = requireDirectory.defaults;

// Modify defaults for all subsequent calls
requireDirectory.defaults.extensions = ['js', 'ts'];

Types

/**
 * Configuration options for requireDirectory function
 */
interface RequireDirectoryOptions {
  /** File extensions to process (default: ['js', 'json', 'coffee']) */
  extensions?: string[];
  /** Enable recursive directory processing (default: true) */
  recurse?: boolean;
  /** Transform function for object keys */
  rename?: (name: string, joined: string, filename: string) => string;
  /** Transform function for loaded modules */
  visit?: (obj: any, joined: string, filename: string) => any;
  /** RegExp pattern or function to include specific files */
  include?: RegExp | ((path: string, filename: string) => boolean);
  /** RegExp pattern or function to exclude specific files */
  exclude?: RegExp | ((path: string, filename: string) => boolean);
}

/**
 * Filter function signature for include/exclude options
 */
type FilterFunction = (path: string, filename: string) => boolean;

/**
 * Rename function signature for transforming object keys
 */
type RenameFunction = (name: string, joined: string, filename: string) => string;

/**
 * Visit function signature for transforming loaded modules
 * Return value is used if truthy, otherwise original object is kept
 */
type VisitFunction = (obj: any, joined: string, filename: string) => any;

Behavior Notes

  • Self-exclusion: The calling module file is automatically excluded from results
  • Empty directories: Directories containing no matching files are excluded from results
  • Key generation: Object keys are generated by removing file extensions from filenames
  • Module loading: Uses module.require() internally for proper relative path resolution
  • Error handling: File system and module loading errors are not caught and will propagate
  • Path resolution: Relative paths are resolved relative to the calling module's directory

Common Patterns

// Route organization pattern
// routes/index.js
module.exports = requireDirectory(module);

// app.js
const routes = require('./routes');
app.get('/', routes.home);
app.get('/users', routes.users.list);

// Controller loading with transformation
const controllers = requireDirectory(module, './controllers', {
  visit: (controller) => {
    // Auto-bind methods to controller instance
    if (typeof controller === 'object') {
      Object.getOwnPropertyNames(Object.getPrototypeOf(controller))
        .filter(name => typeof controller[name] === 'function')
        .forEach(name => controller[name] = controller[name].bind(controller));
    }
    return controller;
  }
});

// Development vs production file loading
const middleware = requireDirectory(module, './middleware', {
  exclude: process.env.NODE_ENV === 'production' ? /dev\.js$/ : /prod\.js$/
});
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/require-directory@2.1.x
Publish Source
CLI
Badge
tessl/npm-require-directory badge