README
Pluginbot
Lightweight, unopinionated plugin framework - create extremely extensible and scalable apps using a service-based architecture and dependency injection.
Overview
At a high level - pluginbot is an app framework that consists of plugins which can provide/consume services. To define a plugin you define a function which provide services and a function that can consume services, consumption happens in the form of a redux-saga so your plugin can wait around for your desired service to be provided which elmiminates dependency chains entirely since your plugin will pause execution until the service it needs becomes available.
This architecture allows for a highly extensible application because a plugin that adds functionality would just provide services other plugins consume (or consume services other plugins provide) - for example a plugin could provide new routes to be consumed by a router plugin or a plugin could provide UI components such as navigation-menus which would be rendered by a navigation-menu consumer.
Configuration
In order for plugins to run, they have to be declared in a configuration which will contain at a minimum the path of the plugin. Here you would define environment specific data.
Configuration can either be json or a js file that exports an object/Promise that resolves to an object
The plugins array represents the enabled plugins in a pluginbot instance.
// ./config.js
//path should be relative to the config file location, or absolute, can refer to NPM modules as well
module.exports = {
plugins: [
{"path": "express-app", "apiBaseUrl" : "/api", "port" : 3001},
{"path": "./route-provider", "port": 3001},
],
};
Plugin Interface
A plugin consists of a module which exports a generator function, each plugin takes the form of a redux-saga meaning they can wait for specific events to happens or services to be provided by other plugins before running their own code.
// ./express-app/express-app.js
//take used for consumption
let express = require("express");
const consume = require("pluginbot/effects/consume");
module.exports = {
/**
* This function is a saga which can consume or provide services and represents a plugin's lifecycle
*
* @param config {Object.<string, Object.<string, *>>}
* - Keys the config option name to the config's value defined in the Pluginbot configuration
*
* @param provide {function(Object)} - provide services, key servicename value service, returns effect
*
* @param services {Object.<string, Channel>} -
* keyed by service name, value is a channel that can be consumed for a service
*/
run : function*(config, provide, services){
const app = express();
const router = express.Router();
app.use(config.apiBaseUrl, router);
app.listen(config.port);
//provide expressApp and baseRouter which can now be consumed by other plugins
yield provide({
expressApp: app,
baseRouter: router
});
//loop pauses when it hits a yield
while(true){
//wait around for new expressRouter services to be provided
let newRoute = yield consume(services.expressRouter);
//add new route to the api router
router.use(newRoute);
}
}
}
Now if I wanted to create a plugin which adds a new route to my app all I need to do is provide an expressRoute service
// ./hello-world/hello-world.js
module.exports = {
run : function*(config, provide, services){
const router = require("express").Router();
//would be called by GET /api/hello-world
router.get("/hello-world", (req, res) => {
res.json({hello : "world"});
});
//provide expressRouter to be used by the app's router
yield provide({
expressRouter: router
});
}
}
package.json
In order for a pluginbot plugin to be considered valid it requires a pluginbot section to be defined in the package.json. For a basic definition you just need to define where the entry point to your plugin is and the services the plugin consumes (if any)
// ./express-app/package.json
{
"name": "express-app",
"version": "0.0.1",
"private": true,
"pluginbot": {
"main" : "express-app.js",
"consumes": ["expressRoute"]
}
}
Starting Pluginbot
To start pluginbot on the server, just call createPluginbot and initialize it
// ./app.js
const CONFIG_PATH = "./config.js"
let path = require("path");
let Pluginbot = require("pluginbot");
//pass full path to createPluginbot
Pluginbot.createPluginbot(path.resolve(__dirname, CONFIG_PATH))
.then(pluginbot => pluginbot.initialize())
.catch(e => {
console.error(e);
});
Advanced (in progress...)
Hooks
On Plugin Install
On Plugin Uninstall
On Plugin Enable
On Plugin Disable
Consume services with React components
see pluginbot-react