Generates routes for Express based on the file structure of route files


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
Minified + gzip package size for @bouncingpixel/express-handler-routing in KB



Generates routes for Express based on the file structure of route files.

Working With


  • NodeJS 6 LTS
  • Express

Using express-handler-routing

To use the package, simply require it in and pass in the path to your routes directory.

Subdirectories will be navigated properly and are loaded after the index.js, but before any other .js file. To create a route for a directory, create an index.js file in that directory. The index.js will be the first file to be loaded within a directory. Alternatively, a .js file in the parent directory using the same name as the directory can be used which will be loaded after the directory. The directory's index route will work with and without the ending slash.

    path.resolve(process.cwd(), 'server/routes/'), // path to the routes directory

Each route file exports one object with the method and handlers for the method. Route files may also contain nested routes to help group similar routes together in a single file. The object keys can be the HTTP method (get, post, head, etc) which will be mounted as a route, use which will mount middleware or an array of middlewares at that route, or a string starting with a forward slash to denote a nested route.

The HTTP method must point to an object which contains at least a key handler pointing to an Express route handler of function(req, res) or function(req, res, next). Optionally, this object may also contain pre and post middlewares.

The routing object may also contain pre and post middleware that is applied to all routes contained within the route file. The pre and post can be defined at any level, including nested routes. pre will run in order down the chain to the handler, then the post will run back up the chain away from the handler.

For example, if we have a file at the path /_site/blogs.js which contains the following route definition:

module.exports = {
  // pre-middleware to run before all routes in this file
  pre: [

  // can also do some post middlewares as well
  post: [],

  get: {
    // handler is a standard Express handler for a route.
    handler: function(req, res) {
        .then((posts) => {
          res.render('blogpost-list', posts);

  // could define the other methods, post, put, etc

  // a nested route for a specific blog post
  '/:id': {
    get: {
      // pre is a set of middleware to run before handler
      pre: [isIdParamValid],

      handler: function(req, res, next) {
          .findOne({_id: req.param.id})
          .then((post) => {
            if (!post) {
              next(new NotFoundError('Could not find the blog post'));
            } else {
              res.render('blogpost', post);

      // post will run after handler if next() is called
      // can be useful for error handling or further processing
      post: [blogNotFoundHandler]

The following routes will be generated:


Load order

  1. index.js file is always loaded first before any directories or files
  2. Directories are loaded second in order of the OS (alphabetical)
  3. all other .js files are loaded afterwards in order of the OS (alphabetical)

As such, if you wish for a behavior to apply to everything within a directory, put it in the index.js. If you wish for a behavior to apply last inside a subdirectory, you may use a file within the parent with the same name.



If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.