lambda-api

Lightweight web framework for your serverless applications

Lambda API is a lightweight web framework for AWS Lambda using AWS API Gateway Lambda Proxy Integration or ALB Lambda Target Support. This closely mirrors (and is based on) other web frameworks like Express.js and Fastify, but is significantly stripped down to maximize performance with Lambda's stateless, single run executions.

Using AWS SDK v2?

lambda-api@v1 is using AWS SDK v3. If you are using AWS SDK v2, please use [email protected].

Simple Example

// Require the framework and instantiate it
const api = require('lambda-api')();

// Define a route
api.get('/status', async (req, res) => {
  return { status: 'ok' };
});

// Declare your Lambda handler
exports.handler = async (event, context) => {
  // Run the request
  return await api.run(event, context);
};

For a full tutorial see How To: Build a Serverless API with Serverless, AWS Lambda and Lambda API.

Why Another Web Framework?

Express.js, Fastify, Koa, Restify, and Hapi are just a few of the many amazing web frameworks out there for Node.js. So why build yet another one when there are so many great options already? One word: DEPENDENCIES.

These other frameworks are extremely powerful, but that benefit comes with the steep price of requiring several additional Node.js modules. Not only is this a bit of a security issue (see Beware of Third-Party Packages in Securing Serverless), but it also adds bloat to your codebase, filling your node_modules directory with a ton of extra files. For serverless applications that need to load quickly, all of these extra dependencies slow down execution and use more memory than necessary. Express.js has 30 dependencies, Fastify has 12, and Hapi has 17! These numbers don't even include their dependencies' dependencies.

Lambda API ships with ZERO required dependencies. None. Zip. Zilch. The only extras are the AWS SDK v3 S3 packages (@aws-sdk/client-s3 and @aws-sdk/s3-request-presigner), declared as optional peer dependencies. They power the built-in S3 file helpers (sendFile(), getLink(), and S3 redirects). Because they're optional, installing Lambda API won't pull them in — npm, pnpm, Yarn, and Bun all skip optional peer dependencies, so your node_modules stays clean unless you install them yourself. And because the S3 client is loaded lazily (only when an S3 helper actually runs), bundlers can safely treat the AWS SDK as external when you don't use those features. See Installation for details.

Lambda API was written to be extremely lightweight and built specifically for SERVERLESS applications using AWS Lambda and API Gateway. It provides support for API routing, serving up HTML pages, issuing redirects, serving binary files and much more. Worried about observability? Lambda API has a built-in logging engine that can even periodically sample requests for things like tracing and benchmarking. It has a powerful middleware and error handling system, allowing you to implement just about anything you can dream of. Best of all, it was designed to work with Lambda's Proxy Integration, automatically handling all the interaction with API Gateway for you. It parses REQUESTS and formats RESPONSES, allowing you to focus on your application's core functionality, instead of fiddling with inputs and outputs.

Single Purpose Functions

You may have heard that a serverless "best practice" is to keep your functions small and limit them to a single purpose. I generally agree since building monolith applications is not what serverless was designed for. However, what exactly is a "single purpose" when it comes to building serverless APIs and web services? Should we create a separate function for our "create user" POST endpoint and then another one for our "update user" PUT endpoint? Should we create yet another function for our "delete user" DELETE endpoint? You certainly could, but that seems like a lot of repeated boilerplate code. On the other hand, you could create just one function that handled all your user management features. It may even make sense (in certain circumstances) to create one big serverless function handling several related components that can share your VPC database connections.

Whatever you decide is best for your use case, Lambda API is there to support you. Whether your function has over a hundred routes, or just one, Lambda API's small size and lightning fast load time has virtually no impact on your function's performance. You can even define global wildcard routes that will process any incoming request, allowing you to use API Gateway or ALB to determine the routing. Yet despite its small footprint, it gives you the power of a full-featured web framework.

Table of Contents

• Simple Example
• Why Another Web Framework?
  • Single Purpose Functions
• Table of Contents
• Installation
• Requirements
• Configuration
• Recent Updates
  • v0.11: API Gateway v2 payload support and automatic compression
  • v0.10: ALB support, method-based middleware, and multi-value headers and query string parameters
• Routes and HTTP Methods
• Returning Responses
  • Async/Await
  • Promises
  • A Note About Flow Control
• Route Prefixing
• Debugging Routes
• REQUEST
• RESPONSE
  • status(code)
  • sendStatus(code)
  • header(key, value [,append])
  • getHeader(key [,asArray])
  • getHeaders()
  • hasHeader(key)
  • removeHeader(key)
  • getLink(s3Path [, expires] [, callback])
  • send(body)
  • json(body)
  • jsonp(body)
  • html(body)
  • type(type)
  • location(path)
  • redirect([status,] path)
  • cors([options])
  • error([code], message [,detail])
  • cookie(name, value [,options])
  • clearCookie(name [,options])
  • etag([boolean])
  • cache([age] [, private])
  • modified(date)
  • attachment([filename])
  • download(file [, filename] [, options] [, callback])
  • sendFile(file [, options] [, callback])
• Enabling Binary Support
• Path Parameters
• Wildcard Routes
• Logging
  • Logging Configuration
  • Log Format
  • Access Logs
  • Logging Levels
  • Custom Logging Levels
  • Adding Additional Detail
  • Serializers
  • Sampling
• Middleware
  • Restricting middleware execution to certain path(s)
  • Specifying multiple middleware
  • Method-based middleware
• Clean Up
• Error Handling
  • Error Types
  • Error Logging
• Namespaces
• CORS Support
• Compression
• Execution Stacks
• Lambda Proxy Integration
• ALB Integration
• Configuring Routes in API Gateway
• Reusing Persistent Connections
• TypeScript Support
• Contributions
• Are you using Lambda API?

Installation

npm i lambda-api --save

Lambda API has no required runtime dependencies. The S3 file helpers (sendFile(), getLink(), and S3 redirects) rely on the AWS SDK v3, which is declared as an optional peer dependency. If you use those features, install the SDK packages alongside Lambda API:

npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner --save

If you don't use the S3 helpers, you can skip this — nothing else in Lambda API touches the AWS SDK. The S3 client is loaded lazily, so even when the SDK is present in your tree, bundlers can mark it as external and leave it out of the bundle.

Releases are published to npm via GitHub Actions using trusted publishing (OIDC), so every published version ships with npm provenance — a signed, verifiable link back to the exact commit and workflow that built it.

Requirements

• AWS Lambda running Node 8.10+
• AWS API Gateway using Proxy Integration

Configuration

Require the lambda-api module into your Lambda handler script and instantiate it. You can initialize the API with the following options: