# @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:

```diff
// 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](https://expressjs.com/en/guide/behind-proxies.html).
  See [trustProxy](#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](./EXAMPLES.md#advanced-trust-proxy-configuration).

#### Example configuration

```js
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.

```js
// 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.

```js
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.

```js
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](./LICENSE.md)

<!-- LINKS -->

[Setup Guide]:docs/setup.md
[Common "Gotchas"]:docs/gotchas.md

[@gasket/plugin-https]:/packages/gasket-plugin-https/README.md
[createServers]:/packages/gasket-plugin-https/README.md#createservers