serverless-http

What is serverless-http?

The serverless-http npm package is a utility that allows you to easily run web frameworks (like Express, Koa, Hapi, etc.) in a serverless environment such as AWS Lambda, Azure Functions, Google Cloud Functions, and more. It acts as a bridge between your web framework and the serverless platform, handling the necessary conversions and integrations.

What are serverless-http's main functionalities?

Express Integration

This feature allows you to run an Express application in a serverless environment. The code sample demonstrates how to set up a simple Express app and export it using serverless-http.

const serverless = require('serverless-http');
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

module.exports.handler = serverless(app);

Koa Integration

This feature allows you to run a Koa application in a serverless environment. The code sample shows how to set up a basic Koa app and export it using serverless-http.

const serverless = require('serverless-http');
const Koa = require('koa');
const app = new Koa();

app.use(async ctx => {
  ctx.body = 'Hello World!';
});

module.exports.handler = serverless(app);

Hapi Integration

This feature allows you to run a Hapi application in a serverless environment. The code sample illustrates how to set up a simple Hapi server and export it using serverless-http.

const serverless = require('serverless-http');
const Hapi = require('@hapi/hapi');
const server = Hapi.server({
  port: 3000,
  host: 'localhost'
});

server.route({
  method: 'GET',
  path: '/',
  handler: (request, h) => {
    return 'Hello World!';
  }
});

module.exports.handler = serverless(server);

Other packages similar to serverless-http

aws-serverless-express

aws-serverless-express is a similar package that allows you to run an Express.js application on AWS Lambda and Amazon API Gateway. It is specifically tailored for AWS services and provides optimizations for running Express applications in this environment. Compared to serverless-http, it is more AWS-centric and may not support other serverless platforms as seamlessly.

lambda-api

lambda-api is a lightweight web framework for AWS Lambda that provides a similar functionality to serverless-http but is designed specifically for Lambda. It offers a more minimalistic approach and is optimized for performance in the AWS Lambda environment. Unlike serverless-http, it does not support other web frameworks like Express or Koa.

middy

middy is a middleware engine for AWS Lambda that allows you to create modular and reusable middleware for your Lambda functions. While it is not a direct replacement for serverless-http, it can be used to achieve similar goals by composing middleware to handle HTTP requests and responses. It provides a more flexible and modular approach compared to serverless-http.

README

serverless-http

Description

This module allows you to 'wrap' your API for serverless use. No HTTP server, no ports or sockets. Just your code in the same execution pipeline you are already familiar with.

Sponsors

Thank you to Upstash for reaching out to sponsor this project!

Upstash: Serverless Database for Redis Serverless Redis with global replication and durable storage Price scales to zero with per request pricing Built-in REST API designed for serverless and edge functions Start for free in 30 seconds!

Support

Supported Frameworks

(* Experimental)

• Node (http.createServer)
• Connect
• Express
• Koa
• Restana
• Sails *
• Hapi *
• Fastify *
• Restify *
• Polka *
• Loopback *

Supported Providers

• AWS
• Azure (Experimental, untested, probably outdated)

Examples

Please check the examples folder!

Usage example using the Koa framework

const serverless = require('serverless-http');
const Koa = require('koa'); // or any supported framework

const app = new Koa();

app.use(/* register your middleware as normal */);

// this is it!
module.exports.handler = serverless(app);

// or as a promise
const handler = serverless(app);
module.exports.handler = async (event, context) => {
  // you can do other things here
  const result = await handler(event, context);
  // and here
  return result;
};

Usage example using the Express framework with Azure

const serverless = require('serverless-http');
const express = require('express');

const app = express();

app.use(/* register your middleware as normal */);

const handler = serverless(app, { provider: 'azure' });
module.exports.funcName = async (context, req) => {
  context.res = await handler(context, req);
}

Other examples

json-server-less-λ - using serverless-http with json-server and serverless framework in AWS

Limitations

Your code is running in a serverless environment. You cannot rely on your server being 'up' in the sense that you can/should not use in-memory sessions, web sockets, etc. You are also subject to provider specific restrictions on request/response size, duration, etc.

Think of this as a familiar way of expressing your app logic, not trying to make serverless do something it cannot.

Contributing

Pull requests are welcome! Especially test scenarios for different situations and configurations.

Further Reading

Here are some more detailed examples and advanced configuration options as well as provider-specific documentation