[6a3a178] | 1 | # require-directory
|
---|
| 2 |
|
---|
| 3 | Recursively 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 | [![NPM](https://nodei.co/npm/require-directory.png?downloads=true&stars=true)](https://nodei.co/npm/require-directory/)
|
---|
| 8 |
|
---|
| 9 | [![build status](https://secure.travis-ci.org/troygoode/node-require-directory.png)](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 |
|
---|
| 21 | 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:
|
---|
| 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
|
---|
| 35 | var requireDirectory = require('require-directory');
|
---|
| 36 | module.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
|
---|
| 42 | var routes = require('./routes');
|
---|
| 43 |
|
---|
| 44 | // snip
|
---|
| 45 |
|
---|
| 46 | app.get('/', routes.home);
|
---|
| 47 | app.get('/register', routes.auth.register);
|
---|
| 48 | app.get('/login', routes.auth.login);
|
---|
| 49 | app.get('/logout', routes.auth.logout);
|
---|
| 50 | ```
|
---|
| 51 |
|
---|
| 52 | The `routes` variable above is the equivalent of this:
|
---|
| 53 |
|
---|
| 54 | ```javascript
|
---|
| 55 | var 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 |
|
---|
| 69 | 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)`:
|
---|
| 70 |
|
---|
| 71 | ```javascript
|
---|
| 72 | var requireDirectory = require('require-directory');
|
---|
| 73 | module.exports = requireDirectory(module, './some/subdirectory');
|
---|
| 74 | ```
|
---|
| 75 |
|
---|
| 76 | For 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
|
---|
| 79 | var requireDirectory = require('require-directory');
|
---|
| 80 | var routes = requireDirectory(module, './routes');
|
---|
| 81 | ```
|
---|
| 82 |
|
---|
| 83 | ## Options
|
---|
| 84 |
|
---|
| 85 | You 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 |
|
---|
| 89 | Whitelisting (either via RegExp or function) allows you to specify that only certain files be loaded.
|
---|
| 90 |
|
---|
| 91 | ```javascript
|
---|
| 92 | var requireDirectory = require('require-directory'),
|
---|
| 93 | whitelist = /onlyinclude.js$/,
|
---|
| 94 | hash = requireDirectory(module, {include: whitelist});
|
---|
| 95 | ```
|
---|
| 96 |
|
---|
| 97 | ```javascript
|
---|
| 98 | var 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 |
|
---|
| 111 | Blacklisting (either via RegExp or function) allows you to specify that all but certain files should be loaded.
|
---|
| 112 |
|
---|
| 113 | ```javascript
|
---|
| 114 | var requireDirectory = require('require-directory'),
|
---|
| 115 | blacklist = /dontinclude\.js$/,
|
---|
| 116 | hash = requireDirectory(module, {exclude: blacklist});
|
---|
| 117 | ```
|
---|
| 118 |
|
---|
| 119 | ```javascript
|
---|
| 120 | var 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
|
---|
| 136 | var 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 |
|
---|
| 143 | The visitor can also transform the objects by returning a value:
|
---|
| 144 |
|
---|
| 145 | ```javascript
|
---|
| 146 | var 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
|
---|
| 156 | var 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
|
---|
| 166 | var 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 |
|
---|