require-directory

What is require-directory?

The require-directory npm package allows you to recursively iterate over all the files in a directory and require them. This is useful for automatically loading scripts, such as routes, models, or configurations, without having to manually require each file.

What are require-directory's main functionalities?

Recursively requiring modules in a directory

This feature allows you to require all modules in a directory and its subdirectories. The 'module' variable refers to the current module, and 'require-directory' will load all modules relative to it.

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

Whitelisting files to require

This feature allows you to specify a regular expression to filter the files to be required. In this example, only files with a '.js' extension will be required.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module, {
  include: /\.js$/
});

Excluding files from being required

This feature allows you to specify a regular expression to exclude certain files from being required. In this example, files ending with '.test.js' will be ignored.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module, {
  exclude: /\.test\.js$/
});

Custom handler for each required module

This feature allows you to provide a custom handler function that is called for each module that is required. In this example, if the exported module is a function, it is invoked.

const requireDirectory = require('require-directory');
const modules = requireDirectory(module, {
  visit: function (obj) {
    if (obj instanceof Function) obj();
  }
});

Other packages similar to require-directory

require-all

The 'require-all' package is similar to 'require-directory' in that it can also load all files within a directory. It provides options to filter files by a regular expression and to map the names of the keys in the returned object. It differs in its API and additional options for directory traversal and naming.

import-fresh

While 'import-fresh' is not used for bulk requiring modules, it allows you to require a module afresh, ensuring that it is not returned from the cache. This is useful for testing or when you need to reload a module's state.

glob

The 'glob' package provides pattern matching for file paths and can be used to find files in a directory that match a given pattern. It does not require the files but can be used in conjunction with 'require' to dynamically load modules that match a pattern.

README

require-directory

Recursively iterates over specified directory, requiring each file, and returning a nested hash structure containing those libraries.

How To Use

Installation (via npm)

$ npm install require-directory

Usage

A common pattern in node.js is to include an index file which creates a hash of the files in its current directory. Given a directory structure like so:

• app.js
• routes/index.js
• routes/home.js
• routes/auth/login.js
• routes/auth/logout.js
• routes/auth/register.js

routes/index.js uses require-directory to build the hash (rather than doing so manually) like so:

var requireDirectory = require('require-directory');
module.exports = requireDirectory(module);

app.js references routes/index.js like any other module, but it now has a hash/tree of the exports from the ./routes/ directory:

var routes = require('./routes');

// snip

app.get('/', routes.home);
app.get('/register', routes.auth.register);
app.get('/login', routes.auth.login);
app.get('/logout', routes.auth.logout);

The routes variable above is the equivalent of this:

var routes = {
  home: require('routes/home.js'),
  auth: {
    login: require('routes/auth/login.js'),
    logout: require('routes/auth/logout.js'),
    register: require('routes/auth/register.js')
  }
};

Note that routes.index will be undefined as you would hope.

Specifying Another Directory

You can specify which directory you want to build a tree of (if it isn't the current directory for whatever reason) by passing it as the second parameter. Not specifying the path (requireDirectory(module)) is the equivelant of requireDirectory(module, __dirname):

var requireDirectory = require('require-directory');
module.exports = requireDirectory(module, __dirname + '/some/subdirectory');

For example, in the example in the Usage section we could have avoided creating routes/index.js and instead changed the first lines of app.js to:

var requireDirectory = require('require-directory');
var routes = requireDirectory(module, __dirname + '/routes');

Blacklisting/Whitelisting

require-directory takes an optional third parameter that defines which files that should not be included in the hash/tree via either a RegExp or a function. If you pass a function in, it should take a single argument (the path to a file) and return true if that file should be included in the tree. If you pass a RegExp it will be considered a blacklist - files that match that RegExp will not be included in the tree:

var blacklist = /dontinclude.js$/;
var requireDirectory = require('require-directory');
var hash = requireDirectory(module, __dirname, blacklist);

var check = function(path){
  if(/dontinclude.js$/.test(path)){
    return false; // don't include
  }else{
    return true; // go ahead and include
  }
};
var requireDirectory = require('require-directory');
var hash = requireDirectory(module, __dirname, check);

Callback

require-directory takes a function as an optional fourth parameter that will be called for each module that is added to module.exports. The function has two arguments, err and the module.

var callback = function(err, mod) {
	// do something with the module, if you'd like
	var done = mod();
};
var requireDirectory = require('require-directory');
var hash = requireDirectory(module, __dirname, null, callback);

Run Unit Tests

$ npm test

License

MIT License

Author

Troy Goode ([e-mail])