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 |
|
---|