@dotcom-reliability-kit/middleware-render-error-info

Express middleware to render error information in a browser in a way that makes local debugging easier and production error rendering more consistent. This module is part of FT.com Reliability Kit.

• Usage
  • renderErrorInfo
  • Configuration options
    • options.logger
    • options.renderer
• Migrating
• Contributing
• License

Usage

Install @dotcom-reliability-kit/middleware-render-error-info as a dependency:

npm install --save @dotcom-reliability-kit/middleware-render-error-info

Include in your code:

import renderErrorInfo from '@dotcom-reliability-kit/middleware-render-error-info';

[!TIP] If you're using this package with TypeScript, we recommend using the following settings in your tsconfig.json file to avoid type errors:

{
    "esModuleInterop": true,
    "module": "nodenext",
    "moduleResolution": "nodenext"
}

renderErrorInfo

The renderErrorInfo function can be used to generate Express middleware which renders an error debugging page in local development and a sensible stripped-back error page in production. This behaviour is customisable via the renderer option.

When the NODE_ENV environment variable is either empty or set to "development" then a full debug page will be rendered. Otherwise only the error status code and message will be output, e.g. 500 Server Error. This ensures that we don't leak important error information in production.

[!CAUTION] This middleware must be added to your Express app after all your application routes – you won't get rendered errors for any routes which are mounted after this middleware.

const app = express();
// App routes go here
app.use(renderErrorInfo());

[!CAUTION] If you're using @dotcom-reliability-kit/middleware-log-errors in your app, it's best to mount the error info middleware after the logging middleware. Otherwise the error will never be logged.

Once you've mounted the middleware, if you're working locally you should now see a detailed error page when you encounter an error in your app (assuming you're relying on the Express error handler to serve errors):

Debug headers

As well as rendering an error page, the middleware also sends an error-fingerprint HTTP header in the response. This contains the error fingerprint and is available in development and production. Inspecting this header on a generic error page can help identify the root cause of an issue.

Configuration options

Config options can be passed into the renderErrorInfo function as an object with any of the keys below.

app.use(renderErrorInfo({
    // Config options go here
}));

options.logger

A logger object which implements a method, warn, which has the following permissive signature:

type LogMethod = (...logData: any) => any;

This is passed directly onto the relevant log-error method in case of an error, see the documentation for that package for more details.

options.renderer

A function used to render an error page to an end-user. This allows you to customise the error rendering behaviour and output different error info in different situations. This function must have the following signature:

type Renderer = (context: {
	error: SerializedError, // An error object serialized by Reliability Kit - the error we're rendering info for
	request: Request, // The Express request object that resulted in the error
	response: Response // The Express response object we're using to output error info with
}) => {
	contentType: string, // The Content-Type header that should be sent alongside the error info
	body: string // The raw response body to send to the end-user
};

This option defaults to undefined meaning that a full debug page will be rendered in development and a stripped back HTML page in production. You can also access these built-in renderers by importing them:

import { renderers } from '@dotcom-reliability-kit/middleware-render-error-info';

• renderers.debugPage is the development-friendly error info page as HTML, including full error information. It must not be used in production.
• renderers.fallback is a production-safe basic HTML error page
• renderers.json is a production-safe implementation of the JSON Error Response specification

[!TIP] If you're providing your own error renderer it's important that you don't reveal too much error information to an end-user. You can customise the behaviour based on the environment by using the app-info package:

import appInfo from '@dotcom-reliability-kit/app-info';

app.use(renderErrorInfo({
   renderer: appInfo.environment === 'development' ? myDevelopmentRenderer : myProductionRenderer
}));

Migrating

Consult the Migration Guide if you're trying to migrate to a later major version of this package.

Contributing

See the central contributing guide for Reliability Kit.

License

Licensed under the MIT license. Copyright © 2022, The Financial Times Ltd.