Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
plugin
✓ plugins:
- serverless-middleware
✗ plugins:
- serverlessMiddleware
Must be added in serverless.yaml plugins section. Plugin registers automatically; no code import needed.
middleware.handler
✓ // handler.js
export const authenticate = async (event, context) => { ... };
✗ module.exports.authenticate = (event, context, callback) => { ... };
Middleware handlers must return a Promise or be async. Callback-style handlers are not supported.
ESM import
✓ import serverlessMiddleware from 'serverless-middleware';
✗ const serverlessMiddleware = require('serverless-middleware');
Since v3.2.0, package supports ES6 import. In TypeScript + webpack, set extensionAlias to avoid build errors.
Install plugin, configure middleware chains in YAML, and define async handlers. Shows auth, main, and error handlers.
npm install serverless-middleware --save-dev
# serverless.yaml
plugins:
- serverless-middleware
provider:
name: aws
runtime: nodejs22.x
functions:
myFunction:
handler: handler.main
middleware:
- auth.authenticate
- then: handler.main
- catch: handler.error
# handler.js
export const authenticate = async (event, context) => {
if (!event.headers.Authorization) {
throw new Error('Unauthorized');
}
return { ...event, auth: true };
};
export const main = async (event) => ({
statusCode: 200,
body: JSON.stringify({ message: 'Hello' }),
});
export const error = async (error, event, context) => ({
statusCode: 500,
body: JSON.stringify({ error: error.message }),
});
Errors
Common errors & fixes
Error: The "middleware" property is not supported by this framework version
Serverless version < 2 or plugin not properly added to plugins array
fixEnsure Serverless v3+ and add 'serverless-middleware' to plugins list in serverless.yaml
Cannot find module 'auth.authenticate'
Middleware path is not a valid file path; plugin expects relative path without extension
fixUse relative path like 'src/auth.authenticate'; ensure file exports the function
TypeError: handler is not a function or its return value is not a Promise
Middleware function does not return a Promise or is undefined
fixEnsure the middleware handler is an async function or returns a Promise
Audit
Dependencies
serverlessrequiredpeer dependency; plugin only works with Serverless v3+