An easy way to include all node.js modules within a directory.


An easy way to include all node.js modules within a directory.

This utility is called by the moduleloader hookin Sails.js.


npm install include-all --save

Low-level synchronous usage

By default, include-allis synchronous, and a bit low-level. There are also asynchronous helper methods (which are a bit higher-level), but more on that in a sec.

First, here are some examples of the low-level, synchronous usage:

Filter by filename or path
var path = require('path');
var includeAll = require('include-all');

var controllers = require('include-all')({
  dirname     :  path.join(__dirname, 'controllers'),
  filter      :  /(.+Controller)\.js$/,
  excludeDirs :  /^\.(git|svn)$/

controllersis now a dictionary with references to all modules matching the filter. The keys are the filenames (minus the extension).

For example:

  PageController: {
    showHomepage: function (req, res) { /*...*/ },

Keep in mind that the case-sensitivity of file and directory names varies between operating systems (Linux/Windows/Mac).

Optional include

Normally, if an error is encountered when requiring/reading/listing files or directories, it is thrown. To swallow that error silently, set optional: true:

var models = require('include-all')({
  dirname     :  path.join(__dirname, 'models'),
  filter      :  /(.+)\.js$/,
  excludeDirs :  /^\.(git|svn)$/,
  optional    :  true

modelsis now a dictionary with references to all modules matching the filter. If __dirname + '/models'doesn't exist, instead of throwing an error, {}is returned.

For example:

  User: {
    attributes: {},
    datastore: 'localDiskDb',

High-level asynchronous usage

The logic from sails-build-dictionarywas migrated here.

When you run require('include-all'), you get a function. Calling that function uses include-all with default settings (and any of the options from the table below may be passed in.)

But there are also a handful of convenience methods exposed as properties of that function. For example:

var includeAll = require('include-all');

// Could just call `includeAll()` for synchronous usage.
// But could also take advantage of ASYNCHRONOUS usage via:
// • includeAll.optional();
// • includeAll.exists();
// • includeAll.aggregate();

Available convenience methods

include-allexposes 3 different methods for asynchronous usage.

The following convenience methods take all the same options as the default includeAllfunction, but they also support a few additionaloptions. Also, since they're asynchronous, they work a bit differently: they use the conventional Node.js "options,cb" function signature.


Build a dictionary of named modules. (fails silently-- returns {} -- if the container cannot be loaded)

This is how most things in the api/folder of Sails apps are loaded (e.g. controllers, models, etc.)

var path = require('path');
var includeAll = require('include-all');

  dirname: path.resolve('api/controllers'),
  filter: /(.+)Controller\.js$/
}, function (err, modules){
  if (err) {
    console.error('Failed to load controllers.  Details:',err);


  // =>
  // (notice that `identity` and `globalId` are added automatically)
  // ```
  //  { page:
  //   { showSignupPage: [Function],
  //     showRestorePage: [Function],
  //     showEditProfilePage: [Function],
  //     showProfilePage: [Function],
  //     showAdminPage: [Function],
  //     showHomePage: [Function],
  //     showVideosPage: [Function],
  //     identity: 'page',
  //     globalId: 'Page' },
  //  user:
  //   { login: [Function],
  //     logout: [Function],
  //     signup: [Function],
  //     removeProfile: [Function],
  //     restoreProfile: [Function],
  //     restoreGravatarURL: [Function],
  //     updateProfile: [Function],
  //     changePassword: [Function],
  //     adminUsers: [Function],
  //     updateAdmin: [Function],
  //     updateBanned: [Function],
  //     updateDeleted: [Function],
  //     identity: 'user',
  //     globalId: 'User' },
  //  video: { identity: 'video', globalId: 'Video' } }
  // ```

Build a dictionary indicating whether the matched modules exist (fails silently-- returns {} if the container cannot be loaded)

This is how Sails detects the existence of views.


Build a single module dictionary by extending {} with the contents of each module. (fail silently-- returns {} if the container cannot be loaded)

This is how sails.configis built from config files.

For example:

  dirname: '/code/brushfire-ch10-end/config/',
  filter: /(.+)\.js$/,
  depth: 1
}, function (err, modules) {
  if (err) { console.error('Error:', err); return; }

  // =>
  //  { blueprints: { actions: false, rest: false, shortcuts: false },
  //    bootstrap: [Function],
  //    connections:
  //     { localDiskDb: { adapter: 'sails-disk' },
  //       someMysqlServer:
  //        { adapter: 'sails-mysql',
  //          user: 'YOUR_MYSQL_USER',
  //          password: 'YOUR_MYSQL_PASSWORD',
  //          database: 'YOUR_MYSQL_DB' },
  //       someMongodbServer: { adapter: 'sails-mongo', host: 'localhost', port: 27017 },
  //       somePostgresqlServer:
  //        { adapter: 'sails-postgresql',
  //          user: 'YOUR_POSTGRES_USER',
  //          password: 'YOUR_POSTGRES_PASSWORD',
  //          database: 'YOUR_POSTGRES_DB' },
  //       myPostgresqlServer:
  //        { adapter: 'sails-postgresql',
  //          host: 'localhost',
  //          user: 'jgalt',
  //          password: 'blahblah',
  //          database: 'brushfire' } },
  //    cors: {},
  //    globals: {},
  //    http: {},
  //    i18n: {},
  //    log: {},
  //    models: { connection: 'localDiskDb', schema: true, migrate: 'drop' },
  //    policies:
  //     { '*': true,
  //       VideoController: { create: [Object] },
  //       UserController:
  //        { login: [Object],
  //          logout: [Object],
  //          removeProfile: [Object],
  //          updateProfile: [Object],
  //          restoreGravatarURL: [Object],
  //          changePassword: [Object],
  //          signup: [Object],
  //          restoreProfile: [Object],
  //          adminUsers: [Object],
  //          updateAdmin: [Object],
  //          updateBanned: [Object],
  //          updateDeleted: [Object] },
  //       PageController:
  //        { showSignupPage: [Object],
  //          showAdminPage: [Object],
  //          showProfilePage: [Object],
  //          showEditProfilePage: [Object],
  //          showRestorePage: [Object] } },
  //    routes:
  //     { 'PUT /login': 'UserController.login',
  //       'GET /logout': 'UserController.logout',
  //       'GET /video': 'VideoController.find',
  //       'POST /video': 'VideoController.create',
  //       'POST /user/signup': 'UserController.signup',
  //       'PUT /user/removeProfile': 'UserController.removeProfile',
  //       'PUT /user/restoreProfile': 'UserController.restoreProfile',
  //       'PUT /user/restoreGravatarURL': 'UserController.restoreGravatarURL',
  //       'PUT /user/updateProfile': 'UserController.updateProfile',
  //       'PUT /user/changePassword': 'UserController.changePassword',
  //       'GET /user/adminUsers': 'UserController.adminUsers',
  //       'PUT /user/updateAdmin/:id': 'UserController.updateAdmin',
  //       'PUT /user/updateBanned/:id': 'UserController.updateBanned',
  //       'PUT /user/updateDeleted/:id': 'UserController.updateDeleted',
  //       'GET /': 'PageController.showHomePage',
  //       'GET /videos': 'PageController.showVideosPage',
  //       'GET /administration': 'PageController.showAdminPage',
  //       'GET /profile': 'PageController.showProfilePage',
  //       'GET /edit-profile': 'PageController.showEditProfilePage',
  //       'GET /restore': 'PageController.showRestorePage',
  //       'GET /signup': 'PageController.showSignupPage' },
  //    session: { secret: 'blahblah' },
  //    sockets: {},
  //    views: { engine: 'ejs', layout: 'layout', partials: true } }


dirnameThe absolute path of a directory to load modules from.
forceWhen set, any past require cache entry will be cleared before re-requiring a module.
optionalif enabled, continue silently and return {} when source directory does not exist or cannot be read. Normally, this throws an error in that scenario. default: false
ignoreRequireFailuresif enabled, continue silently if a require()call throws. This should be used with care! It completely swallows the require error!default: false. This is useful for tolerating malformed node_modules (see
excludeDirsA regular expression used to EXCLUDE directories by name.
depththe maximum level of recursion where modules will be included. Defaults to infinity.
filteronly include modules whose FILENAME matches this regex. default undefined
pathFilteronly include modules whose FULL RELATIVE PATH matches this regex (relative from the entry point directory). default undefined
dontLoadif dontLoadis set to true, don't run the module w/ V8 or load it into memory-- instead, return a tree representing the directory structure (all extant file leaves are included as keys, with their value = true)
flattenif enabled, ALL modules appear as top-level keys in the dictionary-- even those from within nested directories.
keepDirectoryPathOnly relevant if flattenis true. If enabled, this option causes include-all to include the relative paths in the key names (for nested modules from subdirectories path in the key names).

High-Level Options

The following options are only usable in the higher-level asynchronous methods like optional():

identityif disabled, (explicitly set to false) don't inject an identity into the module also don't try to use the bundled identityproperty in the module to determine the keyname in the result dictionary. default: true
useGlobalIdForKeyNameif useGlobalIdForKeyNameis set to true, don't lowercase the identity to get the keyname-- just use the globalId.
replaceExprin identity: use this regex to remove substrings like 'Controller' or 'Service' and replace them with the value of replaceVal
replaceValsee above. default value: ''
aggregateif enabled, include-all will build the result dictionary by merging all of the target modules together. Note: Each module must export a dictionary in order for this to work (e.g. for building a configuration dictionary from a set of config files).


Back in 2012, this was originally forked from felixge's awesome module, require-all(

It adds a few extra capabilities on top:

  • the ability to include-alla directory as optional.
  • the ability to recursively stat a directory, instead of actually requiring the modules (via the dontLoadoption)
  • the ability to filter by path, not just filename (pathFilter)

Since then, it has evolved quite a bit, but the base implementation is still the same.


First, please read through the documentation above. If you have further questions or are having trouble, click here.


To report a bug, click here.


Please observe the guidelines and conventions laid out in the Sails project contribution guidewhen opening issues or submitting pull requests.



Copyright © 2011 Felix GeisendörferCopyright © 2012 Mike McNeil

A core module in the Sails framework since 2012.

The Sails frameworkis free and open-source under the MIT License.




  • 如何决定何时使用ngview或nginclude?

    Breako Breako(提出了一个问题:How to decide when to use...

    2 年前
  • 使用 keep-alive 的 include 和 exclude 无效的一点注意

    最近在使用开发的后台管理项目中,优化 keepalive 的使用方式时遇到了一些问题 优化前使用的 if 判断来控制页面是否可以缓存,这样做页面切换的动画效果不是太理想 优化想使用 inclu...

    9 个月前
  • vue keep-alive include无效

    原文链接: 微信公众号: 大师兄2016 检查版本 确定当前的版本的是 因...

    6 个月前
  • string-includes-x

    Determines whether one string may be found within another string. stringin...

    7 个月前
  • serverless-plugin-include-dependencies

    A Serverless plugin that reduces your packaged function size serverlesspluginincludedependencies ...

    1 个月前
  • rollup-plugin-includepaths

    Rollup plugin to use relative paths in your project files rolluppluginincludepaths Let you use re...

    2 年前
  • posthtml-include

    Include file in HTML NPMnpmnpmurl Depsdepsdepsurl Teststravistravisurl Coveragecovercoverurl ...

    1 年前
  • ng-include with a variable for src

    ChenTsu LinAustin Lovell(提出了一个问题:nginclude with a...

    2 年前
  • markdown-it-include

    Markdownit plugin which adds the ability to include markdown fragment files. markdownitinclude Bu...

    1 年前
  • lodash.includes

    The lodash method exported as a module. lodash.includes v4.3.0 The lodash( m...

    2 年前


扫码加入 JavaScript 社区