Serverless AWS Lambda

Plug & Play AWS Lambda NodeJS development tool with local API Gateway and Application Load Balancer support.

View on Github

Description

AWS Lambda dev tool for Serverless. Allows Express synthax in handlers. Supports packaging, local invoking and offline Application Load Balancer and API Gateway lambda server mocking.

  • Plug & Play (easy to install, configure and use)
  • Highly customizable
  • Functions are bundled by esbuild
  • Offline server uses NodeJS http module
  • Packaging is made by node-archiver

Installation

yarn add -D serverless-aws-lambda
# or
npm install -D serverless-aws-lambda
service: myapp

frameworkVersion: "3"
configValidationMode: error

plugins:
  - serverless-aws-lambda

Usage

Start the offline server

SLS_DEBUG="*" sls aws-lambda -s dev

It is also possible to passe port and watch options from the CLI with --port or -p and --watch or -w.

Command line values will overwrite serverless.yml custom > serverless-aws-lambda values if they are set.

Invoke

Offline server supports ALB and APG endponts.
Appropriate event object is sent to the handler based on your lambda declaration.
However if your declare both alb and http into a single lambda events you have to specify desired server by setting alb or apg inside your request's:

  • header with X-Mock-Type.
  • or in query string with x_mock_type.

Please note that invoking a lambda from sls CLI (sls invoke local -f myFunction) will not trigger the offline server. But you are still able to inject any event with -d 'someData' sls CLI option.

You can also invoke your Lambdas with a custom event object by making a POST request to:
http://localhost:3000/@invoke/myAwsomeLambda\ for aws-sdk Lambda client compatibility it is also possible to request to:
http://localhost:3000/2015-03-31/functions/myAwsomeLambda/invocations

Example with with aws-sdk Lambda Client:

const { LambdaClient, InvokeCommand } = require("@aws-sdk/client-lambda");

const client = new LambdaClient({ region: "PARADISE", endpoint: "http://localhost:3000" });
const DryRun = "DryRun";
const Event = "Event";
const RequestResponse = "RequestResponse";

const cmd = new InvokeCommand({
  FunctionName: "myAwsomeLambda",
  InvocationType: RequestResponse,
  Payload: Buffer.from(JSON.stringify({ foo: "bar" })),
});

client
  .send(cmd)
  .then((data) => {
    data.Payload = new TextDecoder("utf-8").decode(data.Payload);
    console.log(data);
  })
  .catch((error) => {
    // 🥲
    console.log("error", error);
  });

Environment variable

Lambdas are executed in worker threads. Only variables declared in your serverless.yml are injected into process.env except IS_LOCAL, LOCAL_PORT and NODE_ENV


Advanced configuration:

To have more control over the plugin you can passe a config file via configPath param in plugin options:

custom:
  serverless-aws-lambda:
    port: 3000
    watch: true
    configPath: ./config.default

See defineConfig for advanced configuration.


Use Express syntax with your lambdas:

See docs.


Plugins: