setup.md

Express Setup Guide

Normally, the Express server that is set up by Gasket plugins should have everything you need for your application built-in. If you are building a Plugin for Gasket, or have special requirements to customize your server with additional routes and middleware, this guide is for you!

Before you go on, make sure you understand how to author plugins. Whether your custom Express middleware is for a plugin to be shared across multiple apps, or for a standalone plugin used solely by your app, the plugin system is necessary to do any Express app customization.

Middleware lifecycle

After some standard middleware is injected, a plugin can hook the middleware lifecycle and return a middleware or array of middlewares to be added. This hook is passed the typical gasket object as with any hook, and the express instance:

import someMiddleware from 'some-middleware';
import anotherMiddleware from 'another-middleware';

// Sample plugin
export default {
  name: 'sample-plugin',
  hooks: {
    middleware(gasket, app) {
      return [
        someMiddleware({ some: 'options' }),
        anotherMiddleware(app)
      ];
    }
  }
};

Express lifecycle

The express lifecycle is next. This provides an opportunity to do things with the app object directly, like attaching route handlers:

// Sample plugin
export default {
  name: 'sample-plugin',
  hooks: {
    express(gasket, app) {
      app.param('id', require('./form-id-handler'));
      app.post('/submit/:id', require('./handle-form-submits'));
    }
  }
};

ErrorMiddleware lifecycle

Finally, plugins can hook the errorMiddleware lifecycle and return additional middleware(s), typically for error handling.

import errorLoggingClient from 'some-error-logger';

// Sample plugin
export default {
  name: 'sample-plugin'
  hooks: {
    errorMiddleware(gasket) {
      return async (err, req, res, next) => {
        try {
          await errorLoggingClient.logError(err, req);
          next();
        } catch (loggingError) {
          next(loggingError);
        }
      };
    }
  }
};

Lifecycle timing

Remember, if you need any of your injected middleware to come before or after middleware injected by another plugin, use the timing mechanism of the plugin engine. For example, if you need your middleware to access the server-side redux store created by @gasket/plugin-redux, you can do something like this:

import  getFeatureFlags from './get-feature-flags.js';

export default {
  dependencies: ['@gasket/redux'],
  hooks: {
    middleware: {
      timing: {
        after: ['@gasket/redux']
      },
      handler(gasket, app) {
        return async (req, res, next) => {
          try {
            const flags = await getFeatureFlags({
              userId: req.userId,
              locale: req.cookies.market
            });
            req.store.dispatch({
              type: 'SET_FEATURE_FLAGS',
              payload: { flags }
            });
            next();
          } catch (err) {
            next(err);
          }
        }
      }
    }
  }
}

Middleware paths

You can configure which paths middleware will run on by adding the middleware configuration array to your gasket.js. The array is made up of objects with the name of the middleware (Gasket plugin name) you want to configure and an array of path patterns representing the paths to match for this middleware. Pattern matching entries in the array can come in the form of path strings, path pattern strings, and/or regular expressions. Pattern matching logic follows Express's app.use pattern matching.

export default makeGasket({
  middleware: [
    {
      plugin:'gasket-plugin-example', // Name of the Gasket plugin
      paths: ['/api']
    },
    {
      plugin:'@some/gasket-plugin-example',
      paths: [/\/default/]
    },
    {
      plugin: '@another/gasket-plugin-example',
      paths: ['/proxy', /\/home/]
    }
  ]
});