1# require-directory 2 3Recursively iterates over specified directory, `require()`'ing each file, and returning a nested hash structure containing those modules. 4 5**[Follow me (@troygoode) on Twitter!](https://twitter.com/intent/user?screen_name=troygoode)** 6 7[](https://nodei.co/npm/require-directory/) 8 9[](http://travis-ci.org/troygoode/node-require-directory) 10 11## How To Use 12 13### Installation (via [npm](https://npmjs.org/package/require-directory)) 14 15```bash 16$ npm install require-directory 17``` 18 19### Usage 20 21A 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: 22 23* app.js 24* routes/ 25 * index.js 26 * home.js 27 * auth/ 28 * login.js 29 * logout.js 30 * register.js 31 32`routes/index.js` uses `require-directory` to build the hash (rather than doing so manually) like so: 33 34```javascript 35var requireDirectory = require('require-directory'); 36module.exports = requireDirectory(module); 37``` 38 39`app.js` references `routes/index.js` like any other module, but it now has a hash/tree of the exports from the `./routes/` directory: 40 41```javascript 42var routes = require('./routes'); 43 44// snip 45 46app.get('/', routes.home); 47app.get('/register', routes.auth.register); 48app.get('/login', routes.auth.login); 49app.get('/logout', routes.auth.logout); 50``` 51 52The `routes` variable above is the equivalent of this: 53 54```javascript 55var routes = { 56 home: require('routes/home.js'), 57 auth: { 58 login: require('routes/auth/login.js'), 59 logout: require('routes/auth/logout.js'), 60 register: require('routes/auth/register.js') 61 } 62}; 63``` 64 65*Note that `routes.index` will be `undefined` as you would hope.* 66 67### Specifying Another Directory 68 69You 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)`: 70 71```javascript 72var requireDirectory = require('require-directory'); 73module.exports = requireDirectory(module, './some/subdirectory'); 74``` 75 76For example, in the [example in the Usage section](#usage) we could have avoided creating `routes/index.js` and instead changed the first lines of `app.js` to: 77 78```javascript 79var requireDirectory = require('require-directory'); 80var routes = requireDirectory(module, './routes'); 81``` 82 83## Options 84 85You can pass an options hash to `require-directory` as the 2nd parameter (or 3rd if you're passing the path to another directory as the 2nd parameter already). Here are the available options: 86 87### Whitelisting 88 89Whitelisting (either via RegExp or function) allows you to specify that only certain files be loaded. 90 91```javascript 92var requireDirectory = require('require-directory'), 93 whitelist = /onlyinclude.js$/, 94 hash = requireDirectory(module, {include: whitelist}); 95``` 96 97```javascript 98var requireDirectory = require('require-directory'), 99 check = function(path){ 100 if(/onlyinclude.js$/.test(path)){ 101 return true; // don't include 102 }else{ 103 return false; // go ahead and include 104 } 105 }, 106 hash = requireDirectory(module, {include: check}); 107``` 108 109### Blacklisting 110 111Blacklisting (either via RegExp or function) allows you to specify that all but certain files should be loaded. 112 113```javascript 114var requireDirectory = require('require-directory'), 115 blacklist = /dontinclude\.js$/, 116 hash = requireDirectory(module, {exclude: blacklist}); 117``` 118 119```javascript 120var requireDirectory = require('require-directory'), 121 check = function(path){ 122 if(/dontinclude\.js$/.test(path)){ 123 return false; // don't include 124 }else{ 125 return true; // go ahead and include 126 } 127 }, 128 hash = requireDirectory(module, {exclude: check}); 129``` 130 131### Visiting Objects As They're Loaded 132 133`require-directory` takes a function as the `visit` option that will be called for each module that is added to module.exports. 134 135```javascript 136var requireDirectory = require('require-directory'), 137 visitor = function(obj) { 138 console.log(obj); // will be called for every module that is loaded 139 }, 140 hash = requireDirectory(module, {visit: visitor}); 141``` 142 143The visitor can also transform the objects by returning a value: 144 145```javascript 146var requireDirectory = require('require-directory'), 147 visitor = function(obj) { 148 return obj(new Date()); 149 }, 150 hash = requireDirectory(module, {visit: visitor}); 151``` 152 153### Renaming Keys 154 155```javascript 156var requireDirectory = require('require-directory'), 157 renamer = function(name) { 158 return name.toUpperCase(); 159 }, 160 hash = requireDirectory(module, {rename: renamer}); 161``` 162 163### No Recursion 164 165```javascript 166var requireDirectory = require('require-directory'), 167 hash = requireDirectory(module, {recurse: false}); 168``` 169 170## Run Unit Tests 171 172```bash 173$ npm run lint 174$ npm test 175``` 176 177## License 178 179[MIT License](http://www.opensource.org/licenses/mit-license.php) 180 181## Author 182 183[Troy Goode](https://github.com/TroyGoode) ([troygoode@gmail.com](mailto:troygoode@gmail.com)) 184 185
){kind=link}
){kind=link}