require-dir

What is require-dir?

The require-dir npm package allows you to require all files in a directory, making it easier to manage and load multiple modules without having to require each one individually.

What are require-dir's main functionalities?

Basic Usage

This feature allows you to require all files in a specified directory. The returned object will have keys corresponding to the filenames and values being the required modules.

const requireDir = require('require-dir');
const modules = requireDir('./path/to/directory');

Recursive Loading

This feature allows you to recursively require all files in a directory and its subdirectories. The returned object will have nested objects corresponding to the directory structure.

const requireDir = require('require-dir');
const modules = requireDir('./path/to/directory', { recurse: true });

Filtering Files

This feature allows you to filter which files to require based on a custom filter function. In this example, only files ending with '.js' will be required.

const requireDir = require('require-dir');
const modules = requireDir('./path/to/directory', { filter: (filename) => filename.endsWith('.js') });

Other packages similar to require-dir

glob

The glob package allows you to use wildcard patterns to find files and directories. It is more flexible in terms of pattern matching but does not directly require the files like require-dir.

readdirp

The readdirp package provides recursive file and directory listing with filtering options. It is more focused on file system traversal and does not directly require the files.

require-all

The require-all package is very similar to require-dir, allowing you to require all files in a directory. It offers additional options like filtering and mapping filenames to module names.

README

requireDir()

Node helper to require() directories. The directory's files are examined, and each one that can be require()'d is require()'d and returned as part of a hash from that file's basename to its exported contents.

Example

Given this directory structure:

dir
+ a.js
+ b.json
+ c.coffee
+ d.txt

requireDir('./dir') will return the equivalent of:

{ a: require('./dir/a.js')
, b: require('./dir/b.json')
}

And if CoffeeScript has been registered via require('coffee-script/register'), c.coffee will also be returned. Any extension registered with node will work the same way without any additional configuration.

Installation

npm install require-dir

Note that this package is not requireDir — turns out that's already taken! ;)

Usage

Basic usage that examines only directories' immediate files:

var requireDir = require('require-dir');
var dir = requireDir('./path/to/dir');

You can optionally customize the behavior by passing an extra options object:

var dir = requireDir('./path/to/dir', {recurse: true});

Options

recurse: Whether to recursively require() subdirectories too. (node_modules within subdirectories will be ignored.) Default is false.

duplicates: By default, if multiple files share the same basename, only the highest priority one is require()'d and returned. (Priority is determined by the order of require.extensions keys, with directories taking precedence over files if recurse is true.) Specifying this option require()'s all files and returns full filename keys in addition to basename keys. Default is false.

E.g. in the example above, if there were also an a.json, the behavior would be the same by default, but specifying duplicates: true would yield:

{ a: require('./dir/a.js')
, 'a.js': require('./dir/a.js')
, 'a.json': require('./dir/a.json')
, b: require('./dir/b.json')
, 'b.json': require('./dir/b.json')
}

filter: Apply a filter on the filename before require-ing. For example, ignoring files prefixed with dev in a production environment:

requireDir('./dir', {
  filter: function (fullPath) {
    return process.env.NODE_ENV !== 'production' && !fullPath.match(/$dev/);
  }
})

mapKey: Apply a transform to the module base name after require-ing. For example, uppercasing any module names:

requireDir('./dir', {
  mapKey: function (value, baseName) {
    return baseName.toUpperCase();
  }
})

mapValue: Apply a transform to the value after require-ing. For example, uppercasing any text exported:

requireDir('./dir', {
  mapValue: function (value, baseName) {
    return typeof value === 'string' ? value.toUpperCase() : value;
  }
})

Tips

If you want to require() the same directory in multiple places, you can do this in the directory itself! Just make an index.js file with the following:

module.exports = require('require-dir')();   // defaults to '.'

And don't worry, the calling file is always ignored to prevent infinite loops.

TODO

It'd be awesome if this could work with the regular require(), e.g. like a regular require() hook. Not sure that's possible though; directories are already special-cased to look for an index file or package.json.

An ignore option would be nice: a string or regex, or an array of either or both, of paths, relative to the directory, to ignore. String paths can be extensionless to ignore all extensions for that path. Supporting shell-style globs in string paths would be nice.

Currently, basenames are derived for directories too — e.g. a directory named a.txt will be returned as a when recursing — but should that be the case? Maybe directories should always be returned by their full name, and/or maybe this behavior should be customizable. This is hopefully an edge case.

License

MIT. © 2012-2015 Aseem Kishore.

Changelog

1.0.0

• mapValue option added
• mapKey option added
• filter option added
• camelcase option removed, use mapKey to achieve the same functionality