lambda-local

What is lambda-local?

The lambda-local npm package allows you to run and test AWS Lambda functions locally. This can be useful for development and debugging purposes, as it enables you to simulate the AWS Lambda environment on your local machine.

What are lambda-local's main functionalities?

Run Lambda Function Locally

This feature allows you to execute a Lambda function locally by specifying the event, the path to the Lambda function, AWS credentials, and a timeout. The code sample demonstrates how to set up and run a Lambda function locally using lambda-local.

const lambdaLocal = require('lambda-local');
const path = require('path');

lambdaLocal.execute({
    event: require('./event.json'),
    lambdaPath: path.join(__dirname, 'index.js'),
    profilePath: '~/.aws/credentials',
    profileName: 'default',
    timeoutMs: 3000
}).then(function(done) {
    console.log(done);
}).catch(function(err) {
    console.log(err);
});

Simulate AWS Context

This feature allows you to simulate the AWS context object that is passed to Lambda functions. The code sample shows how to define a custom context and use it when executing a Lambda function locally.

const lambdaLocal = require('lambda-local');
const path = require('path');

const context = {
    functionName: 'myLambdaFunction',
    awsRequestId: '1234567890',
    logGroupName: '/aws/lambda/myLambdaFunction',
    logStreamName: '2021/01/01/[$LATEST]abcdef1234567890'
};

lambdaLocal.execute({
    event: require('./event.json'),
    lambdaPath: path.join(__dirname, 'index.js'),
    context: context,
    timeoutMs: 3000
}).then(function(done) {
    console.log(done);
}).catch(function(err) {
    console.log(err);
});

Custom Environment Variables

This feature allows you to set custom environment variables for your Lambda function. The code sample demonstrates how to set an environment variable and use it when running a Lambda function locally.

const lambdaLocal = require('lambda-local');
const path = require('path');

process.env.MY_ENV_VAR = 'myValue';

lambdaLocal.execute({
    event: require('./event.json'),
    lambdaPath: path.join(__dirname, 'index.js'),
    timeoutMs: 3000
}).then(function(done) {
    console.log(done);
}).catch(function(err) {
    console.log(err);
});

Other packages similar to lambda-local

serverless-offline

The serverless-offline package allows you to run Serverless applications and AWS Lambda functions locally. It integrates with the Serverless Framework and provides a more comprehensive local development environment, including support for API Gateway, DynamoDB, and other AWS services. Compared to lambda-local, serverless-offline offers a broader range of features and better integration with the Serverless Framework.

localstack

LocalStack is a fully functional local AWS cloud stack that allows you to develop and test cloud applications offline. It supports a wide range of AWS services, including Lambda, S3, DynamoDB, and more. Compared to lambda-local, LocalStack offers a more comprehensive local AWS environment, making it suitable for testing complex applications that rely on multiple AWS services.

README

Lambda-local

Lambda-local lets you test NodeJS Amazon Lambda functions on your local machine, by providing a simplistic API and command-line tool.

It does not aim to be perfectly feature proof as projects like serverless-offline or docker-lambda, but rather to remain very light (it still provides a fully built Context, handles all of its parameters and functions, and everything is customizable easily).

The main target are unit tests and running lambda functions locally.

Install

npm install -g lambda-local

Build

make build

Or

npm install
npm install --only=dev
npm run build

Usage

• As an API: You can also use Lambda local directly in a script. For instance, it is interesting in a MochaJS test suite in order to get test coverage.
• As a command line tool: You can use Lambda-local as a command line tool.

If you're unsure about some definitions, see Definitions for terminology.

About: API

LambdaLocal

API accessible with:

const lambdaLocal = require("lambda-local");

Or on TypeScript (supported on 1.7.0+):

import lambdaLocal = require("lambda-local");

lambdaLocal.execute(options)

Executes a lambda given the options object, which is a dictionary where the keys may be:

Key name	Description
event	requested event as a json object
lambdaPath	requested path to the lambda function
lambdaFunc	pass the lambda function. You cannot use it at the same time as lambdaPath
profilePath	optional, path to your AWS credentials file
profileName	optional, aws profile name. Must be used with
lambdaHandler	optional handler name, default to handler
region	optional, AWS region, default to us-east-1
timeoutMs	optional, timeout, default to 3000 ms
esm	boolean, marks that the script is an ECMAScript module (use import), default false
environment	optional, extra environment variables for the lambda
envfile	optional, load an environment file before booting
envdestroy	optional, destroy added environment on closing, default to false
verboseLevel	optional, default 3. Level 2 dismiss handler() text, level 1 dismiss lambda-local text and level 0 dismiss also the result.
callback	optional, lambda third parameter callback. When left out a Promise is returned
clientContext	optional, used to populated clientContext property of lambda second parameter (context)

lambdaLocal.setLogger(logger)

lambdaLocal.getLogger()

Those functions allow to access the winston logger used by lambda-local.

API examples

A lot of examples, especially used among Mocha, may be found in the test files over: here

Basic usage: Using Promises

const lambdaLocal = require('lambda-local');

var jsonPayload = {
    'key': 1,
    'another_key': "Some text"
}

lambdaLocal.execute({
    event: jsonPayload,
    lambdaPath: path.join(__dirname, 'path_to_index.js'),
    profilePath: '~/.aws/credentials',
    profileName: 'default',
    timeoutMs: 3000
}).then(function(done) {
    console.log(done);
}).catch(function(err) {
    console.log(err);
});

Basic usage: using callbacks

const lambdaLocal = require('lambda-local');

var jsonPayload = {
    'key': 1,
    'another_key': "Some text"
}

lambdaLocal.execute({
    event: jsonPayload,
    lambdaPath: path.join(__dirname, 'path_to_index.js'),
    profilePath: '~/.aws/credentials',
    profileName: 'default',
    timeoutMs: 3000,
    callback: function(err, data) {
        if (err) {
            console.log(err);
        } else {
            console.log(data);
        }
    },
    clientContext: JSON.stringify({clientId: 'xxxx'})
});

About: CLI

Available Arguments

• -l, --lambda-path <lambda index path> (required) Specify Lambda function file name.
• -e, --event-path <event path> (required --watch is not in use) Specify event data file name.
• -h, --handler <handler name> (optional) Lambda function handler name. Default is "handler".
• -t, --timeout <timeout> (optional) Seconds until lambda function timeout. Default is 3 seconds.
• --esm (optional) Load lambda function as ECMAScript module.
• -r, --region <aws region> (optional) Sets the AWS region, defaults to us-east-1.
• -P, --profile-path <aws profile name> (optional) Read the specified AWS credentials file.
• -p, --profile <aws profile name> (optional) Use with -P: Read the AWS profile of the file.
• -E, --environment <JSON {key:value}> (optional) Set extra environment variables for the lambda
• --wait-empty-event-loop (optional) Sets callbackWaitsForEmptyEventLoop=True => will wait for an empty loop before returning. This is false by default because our implementation isn't perfect and only "emulates" it.
• --envdestroy (optional) Destroy added environment on closing. Defaults to false
• -v, --verboselevel <3/2/1/0> (optional) Default 3. Level 2 dismiss handler() text, level 1 dismiss lambda-local text and level 0 dismiss also the result.
• --envfile <path/to/env/file> (optional) Set extra environment variables from an env file
• --inspect [[host:]port] (optional) Starts lambda-local using the NodeJS inspector (available in nodejs > 8.0.0)
• -W, --watch [port] (optional) Starts lambda-local in watch mode listening to the specified port [1-65535].

CLI examples

# Simple usage
lambda-local -l index.js -h handler -e examples/s3-put.js

# Input environment variables
lambda-local -l index.js -h handler -e examples/s3-put.js -E '{"key":"value","key2":"value2"}'

Running lambda functions as a HTTP Server (Amazon API Gateway payload format version 2.0.)

A simple way you can run lambda functions locally, without the need to create any special template files (like Serverless plugin and SAM requires), just adding the parameter --watch. It will raise a http server listening to the specified port (default is 8008). You can then call the lambda as mentionned here: https://docs.aws.amazon.com/lambda/latest/dg/urls-invocation.html

lambda-local -l examples/handler_gateway2.js -h handler --watch 8008

curl --request POST \
  --url http://localhost:8008/ \
  --header 'content-type: application/json' \
  --data '{
        "key1": "value1",
        "key2": "value2",
        "key3": "value3"
}'
{"message":"This is a response"}

About: Definitions

Event data

Event sample data are placed in examples folder - feel free to use the files in here, or create your own event data. Event data are just JSON objects exported:

// Sample event data
module.exports = {
    foo: "bar"
};

Context

The context object has been sampled from what's visible when running an actual Lambda function on AWS, and the available documentation They may change the internals of this object, and Lambda-local does not guarantee that this will always be up-to-date with the actual context object.

AWS-SDK

As of version 2.0.0, lambda-local no longer packages AWS-SDK in its dependencies. To run a function that makes use of this module, make sure to install it as a dependency in your project.

Other links

• If you are willing to test an app based on the ASK-SDK, have a look at https://github.com/taimos/ask-sdk-test

Development

• Run make to install npm modules. (Required to develop & test lambda-local)
• Run make test to execute the mocha test.
• Run make clean to reset the repository.

License

This library is released under the MIT license.

Changelog

2.1.1 (2023/07/22)

• Bug fix: ESM path on Windows
• Downgrade commander-js