require-folder-tree.js
Utility to require multiple files in a folder tree with flexible options
Current status
API is stable and tests cover all options. No known issues.
Basic usage
requireFolderTree( path [, options] )
To require all the .js
and .json
files in a folder and any sub-folders:
var requireFolderTree = require('require-folder-tree');
var modules = requireFolderTree('/path/to/folder');
If the file structure is:
/
a.js
b.js
c/
d.js
e.js
The returned value is:
{
a: ...,
b: ...,
c: {
d: ...,
e: ...
}
}
Advanced usage
Options can be passed to alter the behaviour.
recurse
When true
, recurses through subfolders and sub-subfolders requiring an entire tree. Set to false
to ignore subfolders.
Defaults to true
.
requireFolderTree('/path/to/folder', { recurse: false });
filterFiles
A regular expression for what files to include. First matching group defines the key used in returned object.
Defaults to /^(.+)\.js(on)?$/
(i.e. include all .js
and .json
files)
requireFolderTree('/path/to/folder', { filterFiles: /^([^_].*)\.js$/ });
filterFolders
A regular expression for what folders to iterate into. First matching group defines the key used in returned object.
Defaults to /^([^\.].*)$/
(i.e. process all folders except those beginning with .
)
requireFolderTree('/path/to/folder', { filterFolders: /^([^\._].*)$/ });
fileNameTransform
Function for transforming object keys for files.
requireFolderTree('/path/to/folder', {
fileNameTransform: function(str) { return str.toLowerCase(); }
});
folderNameTransform
Like fileNameTransform
, but for folder names.
By default, inherits value of options.fileNameTransform
. If you want to define a fileNameTransform
function but leave folder names unchanged, set options.folderNameTransform = null
.
fileNameAttribute
When set, saves the file name (after fileNameTransform
has been applied) as an attribute of each require
-d file.
If true
, uses value 'name'
. Defaults to undefined
.
requireFolderTree('/path/to/folder', { fileNameAttribute: true, recurse: false });
folderNameAttribute
Like fileNameAttribute
, but for folder names.
By default, inherits value of options.fileNameAttribute
. If you want to save file names only, set options.folderNameAttribute = null
.
fileParentAttribute
When set, saves the parent folder as an attribute of each require
-d file.
If true
, uses value 'parent'
. Defaults to undefined
.
requireFolderTree('/path/to/folder', { fileParentAttribute: true, recurse: false });
folderParentAttribute
Like fileParentAttribute
, but for folders.
By default, inherits value of options.fileParentAttribute
. If you want to save file parents only, set options.folderParentAttribute = null
.
flatten
Flattens the folder structure when true
.
Defaults to false
.
requireFolderTree('/path/to/folder', { flatten: true });
flattenPrefix
Controls how the object keys are created for files nested in folders when flattening.
true
concatenates the folder name and file name.
Defaults to false
requireFolderTree('/path/to/folder', { flatten: true, flattenPrefix: true });
flattenCamel
When true
, camel-cases the keys when concatenating the folder name and file name.
Defaults to false
requireFolderTree('/path/to/folder', { flatten: true, flattenCamel: true });
flattenSeparator
Sets separator between folder name and file name when concatenating.
Defaults to undefined
.
requireFolderTree('/path/to/folder', { flatten: true, flattenSeparator: '_' });
flattenCustom
Sets a custom function for combining folder name and file name when concatenating.
Defaults to undefined
.
requireFolderTree('/path/to/folder', {
flatten: true,
flattenCustom: function(a, b) { return a + 'x' + b; }
});
indexFile
If set, looks for the named file in each folder, and if found uses it as a base for the returned object.
Defaults to undefined
.
requireFolderTree('/path/to/folder');
requireFolderTree('/path/to/folder', { indexFile: 'index.js' });
foldersKey
If set, puts all retrieved sub-folders inside the key specified.
Defaults to undefined
.
requireFolderTree('/path/to/folder', { foldersKey: 'folders' });
filesKey
If set, puts all retrieved files inside the key specified.
Defaults to undefined
.
requireFolderTree('/path/to/folder', { filesKey: 'files' });
Tests
Use npm test
to run the tests.
Changelog
See changelog.md
Issues
If you discover a bug, please raise an issue on Github. https://github.com/overlookmotel/require-folder-tree/issues