@blacksmithstudio/blockbase-express NPM

Driver Express for Blockbase

Compatible with Blockbase Framework

Version

0.2.0 alpha

How to install ?

$ npm i --save @blacksmithstudio/blockbase-express

Then add to your config/{env}.yml the following (example) instructions depending of your system

express :
    port: 1340
    body_parser_limit : 50mb
    404_redirect : /404
    routes :
        - type: controller
          src: /foo/bar
          dest: /controllers/foo::bar
          method: get
        - type: view
          src: /
          dest: home
          method: get

Usage

The entire usage of the driver is done by the config/{env}.yml, we've made tried to make it as simple as it need.

Ports

The port is simply handled by the config/{env}.yml file in the port section of express.

express :
    port: 1340
    #...

The example above creates a server on http://localhost:1340

Routing

A route can have two type : controller or view. As it looks like a controller will be a program call (in a app.controller.* controller) and a view will call a view in the folder /views.

The following routes are programmed as described below :

controller ex : creates a route on localhost:1340/foo/bar that will trigger the app.controllers.foo.bar() method on the GET method

      - type: controller
        src: /foo/bar
        dest: /controllers/foo::bar
        method: get

view ex : creates a route on localhost:1340/ that will show the /views/home.twig template on the GET method

      - type: view
        src: /
        dest: home
        method: get

Middlewares

A middleware needs to have a destination dest, and can optionaly have a source src to define the path where to use it. Example :

    - dest: uri-logger
    - dest: cors
      src: /login
    #...

Then, inside the /middleware folder, create a middleware using the following sample :

//cors.js - /login
module.exports = (app) => {
    return function(req, res, next) {
        app.drivers.logger.log(`hello it's Middleware again on /login !`)
        next() //Continue to next middleware/route call
    }
}

Static Assets

Static assets can be stored in /views/assets/* You can then call them directly from the route localhost:port/assets/*

You can override this outside route by adding the assets route config to the express configuration

express :
    assets: /static
    #...

Body Parser

The https://www.npmjs.com/package/body-parser(body parser) is a critical sub-library really useful when creating APIs, it handles the JSON support of the route and will create a security layer on the size of your requests.

You can set up the bodyparser limit with the body_parser_limit parameter. To see what to put inside this key please refer to the https://www.npmjs.com/package/body-parser#limit(lib doc section).

express :
    body_parser_limit: /50mb
    #...

Redirects

The driver handles automatically 404 redirections to improve security and SEO compliance. Just add the route you wanna you for your 404 in the 404_redirect section

express :
    404_redirect: /notfound
    #...
    routes :
        #...
        - type: view
          src: /notfound
          dest: fourOfour
          method: get
    #...

The example above will redirect all 404 responses to /notfound handled by the four0four html template.

Async Init

Due to Blockbase architecture, drivers & models are created before controllers. However if you use controllers related routes, you might need to force Express to wait until the controllers are ready to listen & use addons.

In order to do that, two steps :

Add the boolean async_init to the config/{env}.yml in the express section :

express :
    async_init : true
    #...
    routes :
        #...
        #...

Then manually trigger app.drivers.express.route and app.drivers.express.listen after the app init in the main blockbase callback.

blockbase({ root : __dirname }, (app) => {
    app.drivers.express.route()
    app.drivers.express.listen()
})

Sessions

blockbase-express driver includes a native support of the https://www.npmjs.com/package/express-session driver.

To activate it, you just have to fill the following infos :

express :
    session : true
    session_secret : hereYourSecretKey
    session_redis_host : host to your redis server (default localhost)
    session_redis_port : port to your redis (default 6379)

The session_secret key is mandatory in order to secure your sessions. Try to use a cool rock-solid hash :)

Be also careful redis is mandatory when you use session...