@gasket/plugin-express

Adds Express to your application.

Guides

• Setup Guide for adding middleware and routes.
• Common "Gotchas" encountered with Express middleware.

Installation

npm i @gasket/plugin-express

Update your gasket file plugin configuration:

// gasket.js

+ import pluginExpress from '@gasket/plugin-express';

export default makeGasket({
  plugins: [
+   pluginExpress
  ]
});

Configuration

All the configurations for the plugin are added under express in the config:

• compression: true by default. Can be set to false if applying compression differently.
• trustProxy: Enable trust proxy option, see Express documentation on Express behind proxies. See trustProxy below for the recommended setting.

trustProxy

Set it to the number of proxies in front of the app. true trusts the whole X-Forwarded-For chain, so req.ip becomes whatever the client sent first — any client can prepend its own entry to that header. Leave it unset when nothing sits in front of the app — req.ip is then the socket peer.

A hop count assumes every request passes through the same number of proxies. When paths vary or the app is reachable directly — for example, some traffic reaches the load balancer without the CDN — a client on the shorter path supplies the entry the count selects. Trust the proxies by address instead: an IP or CIDR list such as ['10.0.0.0/8'], or a function — see Advanced Trust Proxy Configuration.

Example configuration

export default makeGasket({
  plugins: [
    pluginExpress
  ],
  express: {
    compression: false,
    trustProxy: 1 // one load balancer in front
  }
});

Route Definition

Routes can be defined in a in-app plugin in the plugins directory. The plugin will hook the express lifecycle to add the routes to the express app.

// plugins/routes-plugin.js
export default {
  name: 'routes-plugin',
  hooks: {
    express: async function (gasket, app) {
      app.get('/hello', (req, res) => {
        res.send('Hello World!');
      });
    }
  }
};

Lifecycles

express

Executed after the middleware event for when you need full control over the express instance.

export default {
  name: 'sample-plugin',
  hooks: {
    /**
    * Update Express app instance
    *
    * @param {Gasket} gasket The Gasket API
    * @param {Express} express Express app instance
    * @returns {function|function[]} middleware(s)
    */
    express: async function (gasket, express) {
    }
  }
};

errorMiddleware

Executed after the express event. All middleware functions returned from this hook will be applied to Express.

export default {
  name: 'sample-plugin',
  hooks: {
    /**
    * Add Express error middlewares
    *
    * @param {Gasket} gasket The Gasket API
    * @returns {function|function[]} error middleware(s)
    */
    errorMiddleware: function (gasket) {
    }
  }
};

How it works

This plugins hooks the createServers lifecycles from @gasket/plugin-https.

License

MIT