@rowanmanning/express-config NPM

@rowanmanning/express-config

A library to configure Express in my preferred way.

const app = configureExpress(express());

What is this?

This is a library which sets a lot of Express configurations and generally gets an Express app closer to being production ready (based on my personal preferences). It includes a lot of pre-configured middleware and a few convenenient additions to Express:

Express configurations like strict and case-sensitive routing enabled by default
A Preact view engine, so that views can be written in JSX
Consistent JSON-based logging with Pino and Pino HTTP
Promisified start() and stop() methods
Helmet to help tick many of the basic security boxes for a production app
Automatically redirect to HTTPS when not on localhost
Automatically parse JSON and URLEncoded request bodies
In-memory sessions set up by default, with the option to configure other session stores
Flash messages for temporary session data
Static serving middleware set up to serve from the public directory
Automatically render an customisable HTML error page

Requirements

This library requires the following to run:

Node.js 18+

Usage

Install with npm alongside Express:

npm install express @rowanmanning/express-config

Load the libraries into your code with a require call:

const express = require('express');
const configureExpress = require('@rowanmanning/express-config');

Call the configure function with an Express app:

const app = express();
configureExpress(app);
// app is now configured

The configured app is also returned, so the following is equivalent:

const app = configureExpress(express());

You can tweak my configurations by passing an options object (documented below) as a second argument:

const app = configureExpress(express(), {
    // Options go here
});

Express extensions

By default, configuring Express adds a few new properties and methods.

`app.log`

The log property of the returned Express app contains a Pino logger. This allows you to log app information in a consistent way:

app.log.info('This is a message logged through Pino');

The Pino logger is also available in the request object of any route handler (via Pino HTTP), and logs will be augmented with request information:

app.get('/', (request, response) => {
    request.log.info('Someone visited the home page');
    request.send('Hello World!');
});

`app.preRoute`

The preRoute property is an array containing all middleware that should be run before any application routes. This includes many of the features outlined in the "What is this?" section of this README. Different middleware can be enabled/disabled.

app.use(app.preRoute);
app.get('/', (request, response) => {
    // etc.
});

`app.postRoute`

The postRoute property is an array containing all middleware that should be run after any application routes. This includes many of the features outlined in the "What is this?" section of this README. Different middleware can be enabled/disabled.

app.get('/', (request, response) => {
  // etc.
});
app.use(app.postRoute);

`app.server`

The server property is set to a Node.js HTTP Server which has been created with the Express application.

`app.start()`

The start method is a promisified version of app.listen. It has exactly the same signature as app.listen except that it returns a promise and auto-logs when the server has started.

app.start(process.env.PORT || 8080).then(() => {
    // All good to go!
});

await app.start();
// All good to go!

`app.stop()`

The stop method is a promisified version of app.server.close. It has exactly the same signature as server.close except that it returns a promise and auto-logs when the server has stopped.

app.close().then(() => {
    // All done
});

await app.close();
// All done

Options

Although most of the configurations have sensible defaults which work for all the apps I build, everything is still configurable by passing an options object as a second argument. The available options are:

`errorPage`

Configuration options to pass into @rowanmanning/render-error-page.

Use an object to change configurations or set to false to disable the render-error-page middleware entirely.

`expressPreact`

Configuration options to pass into express-preact-views.

`helmet`

Configuration options to pass into Helmet.

Use an object to change configurations or set to false to disable Helmet entirely.

`jsonBody`

Configuration options to pass into express.json.

Use an object to change configurations or set to false to disable the express.json middleware entirely

`notFound`

Configuration options to pass into @rowanmanning/not-found.

Use an object to change configurations or set to false to disable the not-found middleware entirely.

`pino`

Configuration options to pass into Pino.

`pinoHttp`

Configuration options to pass into Pino HTTP.

Use an object to change configurations or set to false to disable the pino-http middleware entirely.

`publicPath`

A directory for the Express application's static assets.

`redirectToHttps`

Configuration options to pass into express-http-to-https.

Use an object to change configurations or set to false to disable the express-http-to-https middleware entirely.

`session`

Configuration options to pass into express-session.

The sessionName, sessionSecret, and sessionStore configurations should be used before this, as their values will override any that are passed in the session option.

Use an object to change configurations or set to false to disable the express-session middleware entirely.

`sessionName`

The name of the session cookie. see documentation.

`sessionSecret`

A secret used to sign the session ID cookie. see documentation.

If undefined it will default to a random string but sessions will be invalidated every time the application restarts.

`sessionStore`

A session store object. see documentation.

If undefined it will default to an in-memory session store, but sessions will be cleared every time the application restarts.

`static`

Configuration options to pass into express.static.

Use an object to change configurations or set to false to disable the express.static middleware entirely

`trustProxy`

Configuration option for the express trust proxy setting. Defaults to true.

`urlencodedBody`

Configuration options to pass into express.urlencoded.

Use an object to change configurations or set to false to disable the express.urlencoded middleware entirely.

`viewPath`

A directory or an array of directories for the Express application's views. If an array, the views are looked up in the order they occur in the array.

Full Example

This is what a fully configured app looks like, with all default options and all middleware:

const express = require('express');
const configureExpress = require('@rowanmanning/configure-express');

const app = configureExpress(express(), {
    publicPath: `${__dirname}/public`,
    viewPath: `${__dirname}/views`
});

// Mount the pre-route middleware
app.use(app.preRoute);

app.get('/', (request, response) => {
    response.render('home');
});

// More routes go here

// Mount the post-route middleware
app.use(app.postRoute);

app.start(process.env.PORT || 8080);