v5.0.0 Released! Includes Node.js 24 support and removal of deprecated APIs. See UPGRADE.md for upgrade instructions from v4.

Serverless Express by

Starting a new software project? Check out Code Genie - a Full Stack App Generator that delivers a complete AWS Serverless project with source code, based on your data model. Including:

1. A React Next.js Web App hosted on Amplify Hosting
2. Serverless Express REST API running on API Gateway and Lambda
3. Cognito User Pools for Identity/Authentication
4. DynamoDB Database
5. Cloud Development Kit (CDK) for Infrastructure as Code (IAC)
6. Continuous Integration/Delivery (CI/CD) with GitHub Actions

Serverless Express

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 @codegenie/serverless-express

Quick Start/Example

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

• Lambda function
• Express application
• Serverless Application Model (SAM)/CloudFormation template
• Helper scripts to configure, deploy, and manage your application

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.

AWS

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('@codegenie/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
require('source-map-support/register')
const serverlessExpress = require('@codegenie/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()
  console.log(asyncValue)
  serverlessExpressInstance = serverlessExpress({ app })
  return serverlessExpressInstance(event, context)
}

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

  return setup(event, context)
}

exports.handler = handler

Azure

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('@codegenie/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"
    }
  ]
}

4.x

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, Lambda@Edge, VPC Lattice
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 https://github.com/dougmoscrop/serverless-http
6. Automatic isBase64Encoded without specifying binaryMimeTypes. Use binarySettings to customize. Thanks to @dougmoscrop from https://github.com/dougmoscrop/serverless-http
7. respondWithErrors makes it easier to debug during development
8. Node.js 12+
9. Improved support for custom domain names

See UPGRADE.md to upgrade from aws-serverless-express and @codegenie/serverless-express 3.x

API

binarySettings

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:

ExpressApi:
  Type: AWS::Serverless::Api
  Properties:
    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.

serverlessExpress({
  app,
  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

eventSource

serverless-express natively supports API Gateway, ALB, Lambda@Edge and VPC Lattice (only V2 events - event source AWS_VPC_LATTICE_V2). 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 {
    method,
    path,
    headers
  }
}

function responseMapper ({
  statusCode,
  body,
  headers,
  isBase64Encoded
}) {
  // Your logic here...

  return {
    statusCode,
    body,
    headers,
    isBase64Encoded
  }
}

serverlessExpress({
  app,
  eventSource: {
    get