Lightweight Web Framework for AWS Lambda

1.2.0 · active · verified Sun Apr 19

lambda-api is a zero-dependency, lightweight web framework designed specifically for building serverless applications on AWS Lambda. It supports both AWS API Gateway Lambda Proxy Integration and ALB Lambda Target Support, providing a minimal yet familiar API similar to Express.js or Fastify for routing, middleware, and error handling. Optimized for the stateless, single-run execution model of Lambda, it prioritizes fast cold starts and low memory consumption by eschewing external dependencies. The package is currently at version 1.2.0, with a consistent release cadence of minor versions to introduce new features, enhance TypeScript type definitions, and resolve bugs. Its primary differentiation lies in its minimal footprint and dedicated focus on the unique demands of serverless environments, making it ideal for high-performance, cost-efficient serverless APIs.

Common errors

```
TypeError: Cannot read properties of undefined (reading 's3') OR TypeError: api.s3 is not a function
```
cause The built-in S3 service functionality is being accessed without the required AWS SDK v3 peer dependencies installed, or the `lambda-api` version is incompatible with the installed AWS SDK version.

fix Ensure `lambda-api` is `v1.0.0` or higher, and install `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`. If using `lambda-api@0.12.0` for AWS SDK v2, ensure `aws-sdk` is installed.
```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` syntax in an environment configured for ES Modules (e.g., `"type": "module"` in `package.json`).

fix Change your import statement to `import lambdaApi from 'lambda-api'; const api = lambdaApi();`. Alternatively, ensure your file is treated as CommonJS (e.g., change file extension to `.cjs` or set `"type": "commonjs"` in `package.json`).
```
Error: Cannot find module 'lambda-api' or 'lambda-api/package.json'
```
cause The `lambda-api` package has not been installed or is not resolvable from the current working directory.

fix Run `npm install lambda-api` or `yarn add lambda-api` in your project directory.

Warnings

breaking Version 1.0.0 migrated to AWS SDK v3. If your application uses `lambda-api`'s S3 service functionality, you must ensure `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` (peer dependencies) are installed and your code is updated for SDK v3 syntax.
Fix: Install `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` via npm/yarn. Update any AWS SDK v2 S3 calls to their equivalent AWS SDK v3 syntax. If you must use SDK v2, pin `lambda-api` to `0.12.0`.
gotcha As of v1.0.1, AWS SDK v3 packages (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`) are peer dependencies. They are not bundled with `lambda-api` and must be explicitly installed if your application leverages `lambda-api`'s S3 service.
Fix: Run `npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner` (or `yarn add`) if you intend to use the S3 service provided by `lambda-api`.
deprecated Users still relying on AWS SDK v2 should use `lambda-api@0.12.0`. Version 1.x and above are exclusively built for AWS SDK v3.
Fix: If migrating to AWS SDK v3 is not feasible, restrict `lambda-api` to `0.12.0` in your `package.json` (`"lambda-api": "^0.12.0"`). Otherwise, upgrade your application's SDK usage to v3.
security A prototype pollution vulnerability in the `deepMerge` utility was fixed in version 0.11.2. This could potentially allow an attacker to modify properties of `Object.prototype`, affecting all objects in the application.
Fix: Upgrade to `lambda-api@0.11.2` or any later version (e.g., `1.x.x`) to patch this security vulnerability.

Install

npm install lambda-api npm
yarn add lambda-api yarn
pnpm add lambda-api pnpm

Imports

api

wrong:

import { api } from 'lambda-api'; // Incorrectly assumes named export
const api = new API(); // Incorrectly assumes class constructor

correct:

import lambdaApi from 'lambda-api';
const api = lambdaApi();

The default export is a function that needs to be invoked to get the API instance. For CommonJS, use `const api = require('lambda-api')();`.

API

wrong:

import { API } from 'lambda-api'; // Incorrectly imports the type as a value
import API from 'lambda-api'; // Incorrectly assumes default export is the type

correct:

import type { API } from 'lambda-api';

This is a type-only import for the main API interface, useful for TypeScript projects. Other types like `Request` and `Response` are also available for import.

CommonJS (API instance)

wrong:

const lambdaApi = require('lambda-api');
const api = lambdaApi; // Fails to invoke the factory function
const { api } = require('lambda-api'); // Incorrectly assumes named export

correct:

const api = require('lambda-api')();

For CommonJS modules, the `require` call must be immediately invoked as it exports a factory function that returns the API instance.

Quickstart

This quickstart demonstrates how to initialize `lambda-api`, define a simple GET and POST route, and expose it as an AWS Lambda handler.

import lambdaApi from 'lambda-api';

const api = lambdaApi();

// Define a route that responds with a status object
api.get('/status', async (req, res) => {
  return { status: 'ok', timestamp: new Date().toISOString() };
});

// Define a route that handles a POST request with a body
api.post('/greet', async (req, res) => {
  const name = req.body?.name || 'Guest';
  return { message: `Hello, ${name}!` };
});

// Declare your Lambda handler function
export const handler = async (event, context) => {
  // Run the request through the lambda-api framework
  return await api.run(event, context);
};

view raw JSON →