1.0.6 • Public • Published

Express Convention-Based Routes

This package provides a simple way to define convention-based routes in a Node.js/Express application that are created based on a directory structure.

What's a convention-based Express route? It's a route that is dynamically generated and associated with a "controller" function without having to explicitly code the route yourself (i.e. you don't write code such as app.use('/foo', router)). express-convention-routes creates routes automatically by parsing a convention-based folder structure such as the one below when the server first starts.


This allows application routes to be created without having to write any app.use() code to define the individual routes. Using the previous folder structure, express-convention-routes would create the following routes (and associate them with the appropriate "controller" functions):


Each folder contains a "controller" file that defines the functionality to run for the given route. For example, if you want a root route you'd add a file into the root controllers folder (index.controller.js for example). If you want an api/cart route you'd create that folder structure under the controllers folder (see the folder example above) and add a "controller" file such as cart.controller.js into the api/cart folder. You can name the controller files anything you'd like and they can have as many HTTP actions (GET/POST/PUT/DELETE, etc.) in them as you want.

To get started perform the following steps:

  1. Install the express-convention-routes package locally:

    npm install express-convention-routes

  2. Create a controllers folder at the root of your Express project.

  3. To create a root (/) route, add an index.controller.js file into the folder (you can name the file whatever you'd like). Put the following code into the file:

    module.exports = function (router) {
        router.get('/', function (req, res) {
            res.end('Hello from root route!');

    Note that if you'd like to use a controller class you can do that as well:

    class IndexController {
        constructor(router) {
            router.get('/', this.get.bind(this));
        get(req, res) {
            res.render(__dirname + '/index');
    module.exports = IndexController;
  4. To create a /customers route, create a subfolder under controllers named customers.

  5. Add a customers.controller.js file into the customers folder (you can name the file anything you'd like):

    module.exports = function (router) {
        router.get('/', function (req, res) {
            res.end('Hello from the /customers route!');
  6. Once the routing folder structure is created, add the following code into your express server code (index.js, server.js, etc.) to load the routes automatically based on the folder structure in the "controllers" folder when the Express server starts:

    var express = require('express');
    var app = express();
    var router = require('express-convention-routes');
    router.load(app, {
        // Defaults to "./controllers" but showing for example
        routesDirectory: './controllers', 
        // Root directory where your server is running
        rootDirectory: __dirname,
        //Root url of partial convention routes ('/api/ for instance')
        // Defaults to '/'
        rootDirectory: '/',
        // Do you want the created routes to be shown in the console?
        logRoutes: true
  7. Try out the included sample app by running the following commands:

    • npm install
    • npm start
  8. The sample follows a feature-based approach where the controller and associated view are in the same folder (handlebars is used for the views in the sample). If you prefer the more traditional approach where all of the views live in the "views" folder you can simply move the .hbs files there into the proper folders.

I originally got the idea from ASP.NET MVC (as well as other MVC frameworks)and KrakenJS ( These frameworks automate the process of creating routes so I wanted to do something similar with express-convention-routes.

Package Sidebar


npm i express-convention-routes

Weekly Downloads






Unpacked Size

12.3 kB

Total Files


Last publish


  • danwahlin