Features

• 🔧 Zero configuration needed to get started.
• 🔥 hot module replacement on your controllers
• 🍾 async/await support
• ⚙️ Use as middleware with express or standalone.

TOC

• How to use
  • Setup
    • CLI
    • Locally in project
    • With existing express application
  • Controllers
    • Example
  • Plugins
    • Typescript
    • Write your own plugin
  • Hooks
    • Before
    • After
  • Configuration (optional)
    • Options
    • Config examples
    • Custom Babel Config
  • Contributors

Setup

Installation

CLI

npm install -g hot-controller

or

yarn global add hot-controller

Locally in project

1. npm install hot-controller --save or yarn add hot-controller
2. in your package.json add the following:

   "scripts": {
     ...
     "start": "hot-controller serve",
     "dev": "hot-controller"
   }

With existing express application

1. npm install hot-controller --save or yarn add hot-controller

2. Add the middleware to existing express:

   const hotControllers = require('hot-controller/middleware');
   
   ...
   
   app.use(hotControllers(/* (optional) options */));

Controllers

Create a directory in the root of your project called controllers

All files in this directory will be parsed as a controller with hot-controller.

Example

/controllers/home.js

import { Controller, Route } from 'hot-controller';

// which path it should reside on
@Controller('/api')
export default class HomeController {
  // declare your methods below

  @Route.GET('/') // matches /api
  index(req, res) {
    //
    res.send('Welcome');
  }

  @Route.GET('/about')
  users(req, res) {
    // redirect user to somewhere else
    res.redirect('/somewhere-else');
  }

  @Route.GET('/users/:id') // matches /api/users/:id
  async user(req, res) {
    // this is a async method
    const user = await getUserById(req.params.id); // get the user data
    // send it as json
    res.json({
      user
    });
  }
}

Get more examples in our examples repo

Plugins

hot-controller fully supports plugins and is easily activatable in your config.

We follow the "babel plugin naming scheme". (hot-controller-plugin-[PLUGIN_NAME]) and later in your .controllersrc (or what configuration method you're using) add "plugins": [ "plugin-name" ]

Typescript

To write your controllers in typescript please checkout our very own plugin [hot-controller-plugin-typescript)(https://github.com/hot-controller/hot-controller-plugin-typescript)

Write your own plugin

Writing a plugin for hot-controller is very simple. All it takes is a function.

module.exports = function(events) {
  events.on('after-plugins-init', plugins => {
    // will be fired immediately after all plugins been constructed
  });

  events.on('before-controller', router => {
    // before any controllers will be loaded
    // using "router" argument you can add plugin specific routes or add an express middleware.
  });

  events.on('after-controller', (router, controllers) => {
    // after all controllers has been added to the router
    // its now perfect time to add some error handlers or routes that will not conflict with controllers.
  });
};

Hooks

Your controllers can be even more controlled via hooks. Read more below for before and after

Before

@Controller('/')
class Controller {
  async before(req, res, next) {
    // check acl, push to logs or whatever needed to do before we continue the request

    next(); // dont forget this if you want to continue the request.
  }
}

After

@Controller('/')
class Controller {
  after() {
    // nothing more to do,
    // request already sent to client. but maybe you want to log something.
  }
}

Configuration

There are many ways to configure hot-controller:

• Create a .controllersrc.json

  • Support for .json, .json5, .yaml/.yml (just append extension to .controllersrc, ex: .controllersrc.yml)

• Add controllers section to your package.json file.

Options

{
  /**
   * where is your controllers?
   * type: string
   * default: ./controllers
   */
  "dir": "",

  /**
   * sets the root path for controllers (example: /api)
   * type: string
   * default: /
   */
   "path": "/api",

  /**
   * use plugins
   * type: string[], func[]
   */
  "plugins": []
}

Examples

1. via .controllersrc.json

   {
     "dir": "./api"
   }

2. in package.json

   {
     ...
   
     "controllers": {
       "dir": "./api",
     },
   
     ...
   }

Custom Babel Config

hot-controller allows for custom .babelrc for your controllers. This file is optional.

In order to extend our usage of babel, you can simply define a .babelrc file at the root of your app or in your controllers directory.

Contributors

Thanks goes to these wonderful people (emoji key):

| Philip Oliver💻 📖 🤔 👀 ⚠️ 🔧 | Viktor S📖 💻 | an90dr📖 | Umang G. Patel📖 | | :---: | :---: | :---: | :---: |

This project follows the all-contributors specification. Contributions of any kind welcome!