@untool/express

@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.

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) (pipe)

This is a mixin hook defined by @untool/express that allows you to register Express middlewares 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.

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((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.

inspectServer(app, target) (sequence)

This hook will give you a running, i.e. listening, instance of http.Server or https.Server, depending on your https setting. The second argument, target, will only ever be one of develop and serve. You can, for example, use this hook to register your server with an external load balancing system.

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.

renderLocations() (callable)

With this method you can render HTML pages for all configured locations using a simulated Express server configured using @untool/express' settings. This method returns a Promise resolving to a hash containing the rendered paths.

This method is also exported so that you can use it in your own, non-mixin code. Import it like so: import { renderLocations } 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]
locations	[string]	[]
basePath	string	''
assetPath	string	'<basePath>'
buildDir	string	'<rootDir>/dist'

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
}

locations

Using this setting, you can define the locations used for prerendering of static HTML pages at build time. Simply list all URL paths you want to prerender and call un build -ps.

{
  "locations": ["/foo", "/bar"]
}

basePath

This is the URL base path, i.e. subfolder, your application will be served from.

{
  "basePath": "<name>"
}

assetPath

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

{
  "assetPath": "<basePath>/assets"
}

buildDir

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

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