middyjs/middy

What is Middy

Middy is a middleware engine for AWS Lambda on Node.js. It lets you keep your handler focused on business logic while attaching reusable steps for parsing, validation, auth, observability, error handling, and AWS service integration.

• 52 official packages covering API Gateway, SQS, S3, DynamoDB, SNS, EventBridge, Kinesis, Kafka, WebSockets, and more
• Built-in TypeScript types, Node.js >= 22, ESM
• Tiny core (only @middy/util, plus an optional peer dependency for durable functions), no AWS SDK in core
• Routers for HTTP, WebSocket, and CloudFormation custom resources
• First-class support for AWS Lambda response streaming and durable functions

Install

npm install --save @middy/core
# add only the middlewares you need
npm install --save @middy/http-json-body-parser @middy/http-error-handler @middy/validator

Example

import middy from '@middy/core'
import httpJsonBodyParser from '@middy/http-json-body-parser'
import httpErrorHandler from '@middy/http-error-handler'
import validator from '@middy/validator'
import { transpileSchema } from '@middy/validator/transpile'

const schema = {
  type: 'object',
  properties: {
    body: {
      type: 'object',
      properties: {
        amount: { type: 'number' },
        currency: { type: 'string' }
      },
      required: ['amount', 'currency']
    }
  }
}

const lambdaHandler = async (event) => {
  const { amount, currency } = event.body
  // ... business logic
  return { statusCode: 200, body: JSON.stringify({ ok: true, amount, currency }) }
}

export const handler = middy()
  .use(httpJsonBodyParser())
  .use(validator({ eventSchema: transpileSchema(schema) }))
  .use(httpErrorHandler())
  .handler(lambdaHandler)

When to use Middy

Use Middy for every production Lambda. Production handlers always need the same set of non-functional concerns:

• Input validation at every trust boundary (HTTP body / headers / query, event-source payloads).
• Structured logging and consistent error reporting.
• Mapped HTTP error responses instead of stack traces.
• Secrets and config fetched from a secure store with caching + cold-start prefetch.
• CORS, security headers, response shaping for HTTP APIs.
• Authentication for anything exposed to the internet.
• Partial-batch failure handling for SQS / Kinesis / DynamoDB Streams / Kafka / S3 Batch.
• Graceful pre-timeout responses so clients see 408, not 504.

Middy is how you compose those without copy-pasting them into every handler. The "tiny single handler" exception is a trap - production handlers grow, and you do not want to add validation and error mapping under pressure later.

See When to use Middy, Middy vs raw Lambda, and Middy + AWS Lambda Powertools.

Documentation

• Getting started
• Official middlewares
• Event types and event-source recipes
• Routers (HTTP, WebSocket, CloudFormation)
• Writing custom middlewares
• Recipes
• FAQ

Sponsors

License

Licensed under MIT License. Copyright (c) 2017-2026 will Farrell, Luciano Mammino, and Middy contributors.