lightningspirit / serverless-express

Run serverless applications and REST APIs using your existing Node.js application framework, on top of AWS Lambda and Amazon API Gateway

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.

npm install @vendia/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.

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 }).handler

API

binaryMimeTypes

{
  binaryMimeTypes: ['application/json', 'image/*']
}

Specify content types which should be base64 encoded (e.g images or compressed files). Any value you provide here should also be specified on the API Gateway API. In SAM, this looks like:

ExpressApi:
  Type: AWS::Serverless::Api
  Properties:
    StageName: prod
    BinaryMediaTypes: ['application/json', '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

eventFns

serverless-express natively supports API Gateway, ALB, and Lambda@Edge. If you want to use Express with other AWS Services integrated with Lambda you can provide your own custom request/response mappings via eventFns. 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,
  eventFns: {
    request: requestMapper,
    response: responseMapper
  }
})

log

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) {
      console.info(message, 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()

  res.json(event)
})

4.0.0 Goals

1. ✅ Improved API - Simpler for end user to use and configure; extensible without breaking backwards compatibility or hurting API
2. ✅ Node.js 12+ only - can upgrade dependencies to latest (Jest); can use latest syntax in source and tests; can use server.listening; future-proof for Node.js 10
3. ✅ Promise resolution mode by default
4. ✅ Additional event sources - currently only supports API Gateway Proxy; should also support Lambda@Edge (vendia#152) and ALB; have had a customer request for DynamoDB; should make it easy to provide your own IO mapping function.
   1. Added ALB; requires example refactor.
   2. Need to add Lambda@Edge and example
   3. Need to add example of doing custom resolver (DynamoDB)
5. ✅ Multiple header values - can get rid of set-cookie hack
6. ✅ Configure logging - default winston and allow customers to provide their own; include option to respond to 500s with the stack trace instead of empty string currently
7. ✅Improved documentation
8. ✅ Option to strip base path for custom domains (vendia#86).
9. ✅ Update example to include optional parameter for setting up custom domain

Is AWS serverless right for my app?

Benefits

• Pay for what you use
• No infrastructure to manage
• Auto-scaling with no configuration needed
• Usage Plans
• Caching
• Authorization
• Staging
• SDK Generation
• API Monitoring
• Request Validation
• Documentation

Considerations

• For apps that may not see traffic for several minutes at a time, you could see cold starts
• Cannot use native libraries (aka Addons) unless you package your app on an EC2 machine running Amazon Linux
• Stateless only
• API Gateway has a timeout of 29 seconds, and Lambda has a maximum execution time of 15 minutes.

Loadtesting

npx loadtest --rps 100 -k -n 1500 -c 50 https://xxxx.execute-api.us-east-1.amazonaws.com/prod/users

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