serverless-middleware

3.4.0 verified Sat Apr 25 auth: no javascript

Serverless Framework plugin (v3.4.0) enabling middleware chaining directly in serverless.yaml for AWS Lambda functions. Allows defining pre/post handlers, error catches, and execution termination via context.end(). Supports Node.js 14+ (12x–22x) and ES6 modules since v3.2.0. Differentiator: no code changes required—all wiring in YAML; supports mixed then/catch chains and TypeScript with webpack workaround. Released semi-annually, breaking changes limited to runtime/Serverless major bumps.

Common errors

error Error: The "middleware" property is not supported by this framework version ↓

cause Serverless version < 2 or plugin not properly added to plugins array

fix

Ensure Serverless v3+ and add 'serverless-middleware' to plugins list in serverless.yaml

error Cannot find module 'auth.authenticate' ↓

cause Middleware path is not a valid file path; plugin expects relative path without extension

fix

Use relative path like 'src/auth.authenticate'; ensure file exports the function

error TypeError: handler is not a function or its return value is not a Promise ↓

cause Middleware function does not return a Promise or is undefined

fix

Ensure the middleware handler is an async function or returns a Promise

Warnings

breaking In v3.2.0, drop custom property from function config and use middleware directly ↓

fix Migrate from 'custom.middleware' to 'functions.myFunction.middleware' array.

breaking v1.0.0 drops Node 10 & 12 support, requires Serverless v3 ↓

fix Upgrade to Node 14+ and Serverless v3.

deprecated Node.js 12.x runtime support deprecated in v3.1.0 ↓

fix Migrate to Node 14+ runtime.

gotcha ESM support (v3.2.0) breaks TypeScript + webpack builds without extensionAlias ↓

fix In webpack config, add: resolve: { extensionAlias: { '.js': ['.ts', '.js'] } }

gotcha Middleware using callback-style (3-arg) will not execute; only async/Promise handlers work ↓

fix Convert handlers to async functions or return Promise.

gotcha context.prev contains previous handler's return value; empty if first handler ↓

fix Check context.prev !== undefined before using it.

Install

npm install serverless-middleware

yarn add serverless-middleware

pnpm add serverless-middleware

Imports

plugin
wrong
```
plugins:
  - serverlessMiddleware
```
correct
```
plugins:
  - serverless-middleware
```
Must be added in serverless.yaml plugins section. Plugin registers automatically; no code import needed.

middleware.handler

wrong

module.exports.authenticate = (event, context, callback) => { ... };

correct

// handler.js
export const authenticate = async (event, context) => { ... };

Middleware handlers must return a Promise or be async. Callback-style handlers are not supported.

ESM import
wrong
```
const serverlessMiddleware = require('serverless-middleware');
```
correct
```
import serverlessMiddleware from 'serverless-middleware';
```
Since v3.2.0, package supports ES6 import. In TypeScript + webpack, set extensionAlias to avoid build errors.

Quickstart

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 }),
});