require-all

What is require-all?

The require-all npm package is a utility that allows you to require all files within a directory. This can be particularly useful for loading all modules in a directory without having to require each one individually.

What are require-all's main functionalities?

Require all files in a directory

This feature allows you to require all files in a specified directory. In this example, all files in the 'controllers' directory will be required and stored in the 'controllers' object.

const requireAll = require('require-all');
const controllers = requireAll(__dirname + '/controllers');

Filter files by extension

This feature allows you to filter the files to be required by their extension. In this example, only JavaScript files in the 'controllers' directory will be required.

const requireAll = require('require-all');
const jsFiles = requireAll({
  dirname: __dirname + '/controllers',
  filter: /(.+\.js)$/
});

Recursive directory loading

This feature allows you to recursively require all files in a directory and its subdirectories. In this example, all files in the 'modules' directory and its subdirectories will be required.

const requireAll = require('require-all');
const modules = requireAll({
  dirname: __dirname + '/modules',
  recursive: true
});

Map filenames to module names

This feature allows you to map filenames to module names. In this example, the '.js' extension is removed from the filenames when they are used as keys in the 'controllers' object.

const requireAll = require('require-all');
const controllers = requireAll({
  dirname: __dirname + '/controllers',
  map: function (name, path) {
    return name.replace(/\.js$/, '');
  }
});

Other packages similar to require-all

require-dir

The require-dir package is similar to require-all in that it allows you to require all files in a directory. However, it is less feature-rich and does not support filtering by extension or recursive loading out of the box.

bulk-require

The bulk-require package provides similar functionality to require-all, allowing you to require multiple files at once. It also supports filtering and recursive loading, but its API is slightly different.

include-all

The include-all package is another alternative that allows you to include all files in a directory. It offers similar features such as filtering and recursive loading, but it is designed to work well with the Sails.js framework.

README

require-all

An easy way to require all files within a directory.

Usage

var controllers = require('require-all')({
  dirname     :  __dirname + '/controllers',
  filter      :  /(.+Controller)\.js$/,
  excludeDirs :  /^\.(git|svn)$/,
  recursive   : true
});

// controllers now is an object with references to all modules matching the filter
// for example:
// { HomeController: function HomeController() {...}, ...}

Advanced usage

If your objective is to simply require all .js and .json files in a directory you can just pass a string to require-all:

var libs = require('require-all')(__dirname + '/lib');

Constructed object usage

If your directory contains files that all export constructors, you can require them all and automatically construct the objects using resolve:

var controllers = require('require-all')({
  dirname     :  __dirname + '/controllers',
  filter      :  /(.+Controller)\.js$/,
  resolve     : function (Controller) {
    return new Controller();
  }
});

Alternative property names

If your directory contains files where the names do not match what you want in the resulting property (for example, you want camelCase but the file names are snake_case), then you can use the map function. The map function is called on both file and directory names, as they are added to the resulting object.

var controllers = require('require-all')({
  dirname :  __dirname + '/controllers',
  filter  :  /(.+Controller)\.js$/,
  map     : function (name, path) {
    return name.replace(/_([a-z])/g, function (m, c) {
      return c.toUpperCase();
    });
  }
});

Filtering files

If your directory contains files that you do not want to require, or that you want only a part of the file's name to be used as the property name, filter can be a regular expression. In the following example, the filter is set to /^(.+Controller)\.js$/, which means only files that end in "Controller.js" are required, and the resulting property name will be the name of the file without the ".js" extension. For example, the file "MainController.js" will match, and since the first capture group will contain "MainController", that will be the property name used. If no capture group is used, then the entire match will be used as the name.

var controllers = require('require-all')({
  dirname : __dirname + '/controllers',
  filter  : /^(.+Controller)\.js$/
});

For even more advanced usage, the filter option also accepts a function that is invoked with the file name as the first argument. The filter function is expected to return a falsy value to ignore the file, otherwise a string to use as the property name.

var controllers = requireAll({
  dirname : __dirname + '/controllers',
  filter  : function (fileName) {
    var parts = fileName.split('-');
    if (parts[1] !== 'Controller.js') return;
    return parts[0];
  }
});

Note that empty directories are always excluded from the end result.