@untool/express

 

@untool/express provides both an untool preset and a mixin to set up your project to work with Express.

It does not only provide full featured development and production mode servers, but also a mechanism for rendering static files using Express style middlewares without having to launch an actual server.

@untool/express strives to gracefully handle exceptions and to facilitate infrastructure integration: in case of uncaught middleware errors or upon receiving a SIGTERM signal, the server's close method will be called before exiting the process.

Installation

$ yarn add @untool/express # OR npm install @untool/express

CLI

serve

@untool/express registers a single command using @untool/yargs: serve. As to be expected, this command launches a stand-alone Express server featuring Helmet and a Express' static file server middlewares.

$ un serve -ps

Arguments

-p / --production

If un serve is called with the production argument, untool itself sets the shell environment variable $NODE_ENV to "production". This variable is generally used in lots of places, including Express itself.

$ un serve -p # OR un serve --production

This is equivalent to manually setting $NODE_ENV before calling the actual command. Use whatever works best in your specific setting.

$ NODE_ENV=production un serve

API

@untool/express provides a couple of configurable exports for your convenience: mixin hooks marked with 'callable' below can be called like in the following example example:

const { runServer } = require('@untool/express');
runServer();

If you need to provide config overrides or options to these kinds of calls, you can do so like in the next example.

const { configure } = require('@untool/express');
const { runServer } = configure(configOverrides, options);
runServer();

The above example is functionally equivalent to directly working with @untool/core's bootstrap export.

configureServer(app, middlewares, mode) (sequence)

This is a mixin hook defined by @untool/express that allows you to register Express middlewares or route handlers and generally do whatever you like with app, the Application instance it is using under the hood.

The second argument it is being called with is middlewares. It is a plain object containing middleware Arrays sorted into phases: initial, files, parse, routes, and final. Additionally, each of these comes with pre and post variants. Use these phases-arrays to declaratively add middlewares and route handlers to our server.

Its third argument is mode, and it can be one of the following: develop, serve, or static. Use it to conditionally register middlewares or reconfigure the app.

const { Mixin } = require('@untool/core');

module.exports = class MyMixin extends Mixin {
  configureServer(app, middlewares, mode) {
    middlewares.routes.push((req, res, next) => next());
    if (mode === 'serve') {
      middlewares.preinitial.unshift((req, res, next) => next());
      middlewares.postfinal.push({
        path: '/foo',
        method: 'get',
        handler: (req, res, next) => next(),
      });
    }
    return app;
  }
};

Implement this hook in your @untool/core core mixin and you will be able to set up Express in any way you like.

Caveat: please do not rely on the exact number and order of middlewares and handlers passed to your mixin in the middlewares argument: it is highly dynamic and can be altered by other mixins (or configs). It can also change between @untool/express versions without triggering a major release.

inspectServer(server) (sequence)

This hook will give you a running, i.e. listening, instance of http.Server or https.Server, depending on your https setting. This server will emit an additional shutdown event in case a graceful shutdown is triggered.

runServer(mode) (callable)

If you want to programmatically start a production ready Express server set up using @untool/express' config, you can use this utility mixin method. It accepts a string: serve or develop.

This method is also exported so that you can use it in your own, non-mixin code. Import it like so: import { runServer } from '@untool/express';. In this mode, it also accepts another argument, options, which you can pass any CLI argument to.

createServer(mode) (callable)

To create an Express app to use in your own server, you can use this utility mixin method. It uses @untool/express' settings for its configuration. It accepts a string: serve, develop or static.

This method is also exported so that you can use it in your own, non-mixin code. Import it like so: import { createServer } from '@untool/express';. In this mode, it also accepts another argument, options, which you can pass any CLI argument to.

createRenderer() (callable)

If you need a fully configured render function like the one used in renderLocations() (see below), you can call this utility mixin method.

This method is also exported so that you can use it in your own, non-mixin code. Import it like so: import { createRenderer } from '@untool/express';. In this mode, it also accepts another argument, options, which you can pass any CLI argument to.

Settings

@untool/express defines a couple of settings as a preset for @untool/core's configuration engine. You can manage and access them using the mechanisms outlined there.

Property	Type	Default
https	boolean/Object	false
host	string	[HOST]
port	number	[PORT]
distDir	string	'<rootDir>/dist'
gracePeriod	number	30000

https

@untool/express fully supports HTTPS and using this key, you can configure its SSL/TLS mode. You can either set it to true to enable SSL with the included insecure certificate. Or you can tell it to use a proper SSL certificate.

{
  "https": {
    "keyFile": "./ssl/foo.key",
    "certFile": "./ssl/foo.cert"
  }
}

host

The hostname to bind the server to is, of course, configurable. By default, @untool/express tries to read an environment variable named $HOST and falls back to '0.0.0.0'.

{
  "host": "10.10.10.10"
}

port

The TCP port the server will be listening on can be configured, too. By default, @untool/express tries to read an environment variable named $PORT and falls back to a dynamically chosen free port (>=8080).

{
  "port": 3000
}

distDir

This is the file system path, i.e. subfolder, your application's assets will be served from.

{
  "distDir": "<rootDir>/build"
}

gracePeriod

The amount of time (in milliseconds) to wait after receiving a SIGTERM signal or catching an unhandled middleware exception and before killing the server completely.

{
  "gracePeriod": 60000
}