Serverless Express

Run Node.js web applications and APIs using existing application frameworks on AWS #serverless technologies such as Lambda, API Gateway, [email protected], and ALB.
Alternatives To Serverless Express
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Ice17,4987213 days ago84August 26, 2022266mitTypeScript
🚀 ice.js: The Progressive App Framework Based On React(基于 React 的渐进式应用框架)
Serverless Application Model8,95384153 days ago59June 07, 2022133apache-2.0Python
The AWS Serverless Application Model (AWS SAM) transform is a AWS CloudFormation macro that transforms SAM templates into CloudFormation templates.
Crossplane6,7803718 hours ago122September 14, 2022130apache-2.0Go
Cloud Native Control Planes
Micronaut Core5,63826520 hours ago116September 09, 2022600apache-2.0Java
Micronaut Application Framework
Kubevela4,97663 days ago504September 20, 2022402apache-2.0Go
The Modern Application Platform.
Serverless Stack Com3,654
2 days ago121mitSCSS
An open source guide for building and deploying full-stack apps using Serverless and React on AWS.
Stacks Blockchain2,7691112 days ago21May 23, 2016137gpl-3.0Rust
The Stacks blockchain implementation
a month ago112other
Open Application Model (OAM).
3 years ago50apache-2.0Python
AppScale is an easy-to-manage serverless platform for building and running scalable web and mobile applications on any infrastructure.
Formio1,701552 days ago672July 15, 2022348osl-3.0JavaScript
A Form and Data Management Platform for Progressive Web Applications.
Alternatives To Serverless Express
Select To Compare

Alternative Project Comparisons

Serverless Express by Vendia

Build Status npm npm Contributor Covenantdependencies Status

vendia logo

Run REST APIs and other web applications using your existing Node.js application framework (Express, Koa, Hapi, Sails, etc.), on top of AWS Lambda and Amazon API Gateway or Azure Function.

npm install @vendia/serverless-express

Quick Start/Example

Want to get up and running quickly? Check out our basic starter example that includes:

If you want to migrate an existing application to AWS Lambda, it's advised to get the minimal example up and running first, and then copy your application source in.


Minimal Lambda handler wrapper

The only AWS Lambda specific code you need to write is a simple handler like below. All other code you can write as you normally do.

// lambda.js
const serverlessExpress = require('@vendia/serverless-express')
const app = require('./app')
exports.handler = serverlessExpress({ app })

Async setup Lambda handler

If your application needs to perform some common bootstrap tasks such as connecting to a database before the request is forward to the API, you can use the following pattern (also available in this example):

// lambda.js
const serverlessExpress = require('@vendia/serverless-express')
const app = require('./app')

let serverlessExpressInstance

function asyncTask () {
  return new Promise((resolve) => {
    setTimeout(() => resolve('connected to database'), 1000)

async function setup (event, context) {
  const asyncValue = await asyncTask()
  serverlessExpressInstance = serverlessExpress({ app })
  return serverlessExpressInstance(event, context)

function handler (event, context) {
  if (serverlessExpressInstance) return serverlessExpressInstance(event, context)

  return setup(event, context)

exports.handler = handler


Async Azure Function v3/v4 handler wrapper

The only Azure Function specific code you need to write is a simple index.js and a function.json like below.

// index.js
const serverlessExpress = require('@vendia/serverless-express')
const app = require('./app')
const cachedServerlessExpress = serverlessExpress({ app })

module.exports = async function (context, req) {
  return cachedServerlessExpress(context, req)

The out-binding parameter "name": "$return" is important for Serverless Express to work.

// function.json
  "bindings": [
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "route": "{*segments}"
      "type": "http",
      "direction": "out",
      "name": "$return"


  1. Improved API - Simpler for end-user to use and configure.
  2. Promise resolution mode by default. Can specify resolutionMode to use "CONTEXT" or "CALLBACK"
  3. Additional event sources - API Gateway V1 (REST API), API Gateway V2 (HTTP API), ALB, [email protected]
  4. Custom event source - If you have another event source you'd like to use that we don't natively support, check out the DynamoDB Example
  5. Implementation uses mock Request/Response objects instead of running a server listening on a local socket. Thanks to @dougmoscrop from dougmoscrop/serverless-http
  6. Automatic isBase64Encoded without specifying binaryMimeTypes. Use binarySettings to customize. Thanks to @dougmoscrop from dougmoscrop/serverless-http
  7. respondWithErrors makes it easier to debug during development
  8. Node.js 12+
  9. Improved support for custom domain names

See to upgrade from aws-serverless-express and @vendia/serverless-express 3.x



Determine if the response should be base64 encoded before being returned to the event source, for example, when returning images or compressed files. This is necessary due to API Gateway and other event sources not being capable of handling binary responses directly. The event source is then responsible for turning this back into a binary format before being returned to the client.

By default, this is determined based on the content-encoding and content-type headers returned by your application. If you need additional control over this, you can specify binarySettings.

  binarySettings: {
    isBinary: ({ headers }) => true,
    contentTypes: ['image/*'],
    contentEncodings: []

Any value you provide here should also be specified on API Gateway API. In SAM, this looks like:

  Type: AWS::Serverless::Api
    StageName: prod
    BinaryMediaTypes: ['image/*']

resolutionMode (default: 'PROMISE')

Lambda supports three methods to end the execution and return a result: context, callback, and promise. By default, serverless-express uses promise resolution, but you can specify 'CONTEXT' or 'CALLBACK' if you need to change this. If you specify 'CALLBACK', then context.callbackWaitsForEmptyEventLoop = false is also set for you.

  resolutionMode: 'CALLBACK'

respondWithErrors (default: process.env.NODE_ENV === 'development')

Set this to true to have serverless-express include the error stack trace in the event of an unhandled exception. This is especially useful during development. By default, this is enabled when NODE_ENV === 'development' so that the stack trace isn't returned in production.

Advanced API


serverless-express natively supports API Gateway, ALB, and [email protected] If you want to use Express with other AWS Services integrated with Lambda you can provide your own custom request/response mappings via eventSource. See the custom-mapper-dynamodb example.

function requestMapper ({ event }) {
  // Your logic here...

  return {

function responseMapper ({
}) {
  // Your logic here...

  return {

  eventSource: {
    getRequest: requestMapper,
    getResponse: responseMapper


A single function can be configured to handle additional kinds of AWS events:

  • SNS
  • DynamoDB Streams
  • SQS
  • EventBridge Events (formerlly CloudWatch Events)

Assuming the following function configuration in serverless.yml:

    handler: src/lambda.handler
      - http:
          path: /
          method: get
      - sns:
          topicName: my-topic
      - stream:
          type: dynamodb
          arn: arn:aws:dynamodb:us-east-1:012345678990:table/my-table/stream/2021-07-15T15:05:51.683
      - sqs:
          arn: arn:aws:sqs:us-east-1:012345678990:myQueue
      - eventBridge:
              - aws.cloudformation

And the following configuration:

  eventSourceRoutes: {
    'AWS_SNS': '/sns',
    'AWS_DYNAMODB': '/dynamodb',
    'AWS_SQS': '/sqs'
    'AWS_EVENTBRIDGE': '/eventbridge',
    'AWS_KINESIS_DATA_STREAM': '/kinesis',

Alternatively, to handle only SNS events (the keys in the map are optional)

  eventSourceRoutes: {
    'AWS_SNS': '/sns',

Events will POST to the routes configured.

Also, to ensure the events propagated from an internal event and not externally, it is highly recommended to ensure the Host header matches:

  • SNS:
  • DynamoDB:
  • SQS:
  • EventBridge:
  • KinesisDataStream:


Specify log settings that are passed to the default logger. Currently, you can only set the log level.

  logSettings: {
    level: 'debug' // default: 'error'


Provide a custom log object with info, debug and error methods. For example, you could override the default with a Winston log instance.

  log: {
    info (message, additional) {, additional)
    debug (message, additional) {
      console.debug(message, additional)
    error (message, additional) {
      console.error(message, additional)

Accessing the event and context objects

This package exposes a function to easily get the event and context objects Lambda receives from the event source.

const { getCurrentInvoke } = require('@vendia/serverless-express')
app.get('/', (req, res) => {
  const { event, context } = getCurrentInvoke()


Why run Express in a Serverless environment


npx loadtest --rps 100 -k -n 1500 -c 50

AWS Serverless Express has moved

On 11/30, the AWS Serverless Express library moved from AWS to Vendia and will be rebranded to @vendia/serverless-express. Similarly, the aws-serverless-express NPM package will be deprecated in favor of @vendia/serverless-express.

Brett, the original creator of the Serverless Express library, will continue maintaining the repository and give it the attention and care it deserves. At the same time, we will be looking for additional contributors to participate in the development and stewardship of the Serverless Express library. AWS and the SAM team will remain involved in an administrative role alongside Vendia, Brett, and the new maintainers that will join the project.

We believe this is the best course of action to ensure that customers using this library get the best possible support in the future. To learn more about this move or become a maintainer of the new Serverless Express library, reach out to us through a GitHub issue on this repository.

Best, The AWS Serverless team, Brett & the Vendia team

Popular Application Projects
Popular Serverless Projects
Popular Applications Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Amazon Web Services
Lambda Functions
Aws Lambda
Api Gateway
Serverless Framework
Serverless Applications