Custom Express middleware
Contents
Custom Express middleware#
Volto uses the popular Express server for its server-side rendering implementation and static resource serving. In some cases it is useful to extend this server with new functionality. For example, Volto includes a middleware that proxies the backend and that can be used during development. Other use cases might include a CORS proxy server, a proxy to protect a database such as ElasticSearch or MongoDB, etc.
To add new middleware, use the settings.expressMiddleware
configuration
key. This is a list that takes Express middleware functions. For example:
import {
settings as defaultSettings,
} from '@plone/volto/config';
const settings = { ...defaultSettings };
if (__SERVER__) {
const express = require('express');
const middleware = express.Router();
middleware.all('/test-middleware', function (req, res, next) {
res.send('Hello world');
});
middleware.id = 'test-middleware'
settings.expressMiddleware = [
...defaultSettings.expressMiddleware,
middleware,
] ;
}
Now the test-middleware page can be visited and it will return the simple string and not the usual Volto pages.
Static middleware#
The staticMiddleware
is for serving static files such as style sheets and client-side JavaScript files from the BUILD_DIR/PUBLIC
or PUBLIC_DIR
directory.
It uses the express.static()
function to serve static files, and the setHeaders()
function to add response headers to the files that it serves.
import { settings as defaultSettings } from '@plone/volto/config';
import express from 'express';
const settings = { ...defaultSettings };
if (__SERVER__) {
const customStaticMiddleware = express.static('test/static/files');
function setCustomHeaders(req, res, next) {
res.setHeader('Cache-Control', 'public, max-age=3600');
next();
}
customStaticMiddleware.setHeaders = setCustomHeaders;
customStaticMiddleware.id = 'custom-static-middleware';
settings.expressMiddleware = [
...defaultSettings.expressMiddleware,
customStaticMiddleware,
];
}
Function setHeaders(path)
#
The setHeaders()
function is used to update the response headers for a file.
It takes the path of the file being served as an argument, and adds the response headers to that file.
It uses the config
object specified in config.settings.serverConfig.staticFiles
to determine which response headers should be added to the file.
Configuration#
The config.settings.staticFiles
is an array of objects with three properties:
id
a string identifier for the static file rule
match
a regular expression that evaluates the path of the requested resource
headers
an object containing the headers added if the match is successful
The following example shows how to add the response header Cache-Control: public, max-age=3600
to a file named styles.css
located in the BUILD_DIR/PUBLIC
directory:
import {
settings as defaultSettings,
} from '@plone/volto/config';
const settings = { ...defaultSettings };
settings.staticFiles = [
...defaultSettings.staticFiles, {
id: 'styles_css',
match: /^\/styles\.css$/,
headers: {
'Cache-Control': 'public, max-age=3600',
},
}
]
The rules are checked in sequential order, and the search stops at the first match.
The default rules add headers that set the browser cache to 365 days for resources under the /static
path and 60 seconds for all other paths.
Notice the use of the __SERVER__
condition. Because the code in a Volto
project's config.js
gets executed by both the server and the client
(browser), the server-side libraries need to "excluded" with conditions.
See ExpressJS website for more documentation.
Note
Addon authors should add the id
property to the middleware so that it
can be identified and manipulated in Volto projects configuration.