node package manager


Travis CI badge


XREQUIRE is your index.js folder loader swiss army knife.

$ npm install xrequire --save

Obligatory feature checklist (and API documentation all in one):

  • Implement your index.js in a single line:
  • Or the more common style found with other libs:
module.exports = require('xrequire')(__dirname)
  • Post-process modules on the fly by passing a map function:
require('xrequire')(module, function(exports, name, basename) {
  // hidden base class 
  function Base() { }
  Base.prototype = new Object();
  // inject base class and other shared dependencies 
  return exports(Base, require('underscore'), require('async'));
  • Filters module by passing a filter function:
  { filter:
    function(name) {
      return name[0] !== '_'; // modules with _ prefix should be hidden 
  • Or reject works too:
  { reject:
    function(name) {
      return name[0] === '_'; // modules with _ prefix should be hidden 
  • Append (or prepend) a namespace-specific name to your classes without having long filenames:
// assume we have roles/admin.js roles/staff.js and roles/guest.js 
// we'll get adminRole, staffRole and guestRole exports 
require('xrequire')(module, { append: 'Role' });
  • Transform your file names into ClassNames dasherized-name or even "Titleized Long Strings Keys" via an integrated pksunkara/inflect hook:
require('xrequire')(module, { inflect: 'classify' }); // or ... 
require('xrequire')(module, { inflect: 'dasherize' }); // or ... 
require('xrequire')(module, { inflect: 'titleize' }); // or ... 
// other i.hooks works too. 
  • The last two options together provide some nice naming capability out of the box:
require('xrequire')(module, { inflect: 'classify', append: 'Role' })
// assume we have roles/admin.js roles/staff.js and roles/guest.js 
// we'll get AdminRole, StaffRole and GuestRole all neat and clean :) 
  • Implemented in pure JS with high test coverage (yeah, there wasn't much to be tested anyway.)
$ make cover


Default option values are as follows:

{ filter: function(name) { return true; }     // function : return true to include only wanted modules 
, reject: function(name) { return false; }    // function : return true to reject select modules 
, map: function(exports) { return exports; }  // function : transform module exports (useful w/ function() exports) 
, extensions: 'js|coffee|litcoffee|node' // string or array : valid file extensions 
, prepend: ''   // string   : prepend to module names before exported 
, append: ''    // string   : append to module names before exported 
, inflect: ''   // string   : name of inflection method to use 
, magic: true   // boolean  : set to false to prevent module.exports magic 


The xrequire main export object mixes in methods from an EventEmitter and will emits a require event whenever a file is about to be require-ed. You can add a listener to this event to adds logging, for example.

var xrequire = require('xrequire');
xrequire.on('require', function(filePath, name) {

The handler is given two arguments, the resolved path of the file being required and the extracted name that would be used as key of the resulting hash.


Test xrequire by running

$ make test

and generate coverage reports by running

$ make cover

Things to do:

  • Subfolder requires.
  • Support for folder requires without needing to implement index.js.
  • More inflection tests and validation.
  • Direct name transform function.




Just open a GitHub issue or ping me on twitter @chakrit