• Stars
    star
    1,353
  • Rank 34,729 (Top 0.7 %)
  • Language
    JavaScript
  • License
    BSD 2-Clause "Sim...
  • Created almost 10 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Command line tool to locally run and deploy your node.js application to Amazon Lambda

If you found this useful, consider also checking out dotenv-vault. Thank you! 😇

node-lambda

node-lambda

Command line tool to locally run and deploy your node.js application to Amazon Lambda.

Node CI NPM version

$ node-lambda run

Installation

With npx:

$ npx node-lambda@latest [COMMAND]

Globally installed:

$ npm install -g node-lambda

Example App

Example apps make it easy to get up and running

Usage

There are 4 available commands.

$ npx node-lambda@latest setup
$ npx node-lambda@latest run
$ npx node-lambda@latest package
$ npx node-lambda@latest deploy

Commands

setup

Initializes the event.json, context.json, .env, deploy.env files, and event_sources.json files. event.json is where you mock your event. context.json is where you can add additional mock data to the context passed to your lambda function. .env is where you place your deployment configuration. deploy.env has the same format as .env, but is used for holding any environment/config variables that you need to be deployed with your code to Lambda but you don't want in version control (e.g. DB connection info). event_sources.json is used to set the event source of the Lambda function (Not all event sources available in Lambda are supported).

$ npx node-lambda@latest setup --help

Usage: setup [options]

Sets up the .env file.


Options:
  -h, --help                        output usage information
  -j, --eventFile [event.json]      Event JSON File
  -x, --contextFile [context.json]  Context JSON File

After running setup, it's a good idea to gitignore the generated event.json and .env files, as well as .lambda.

$ echo -e ".env\ndeploy.env\nevent.json\n.lambda" >> .gitignore
Deploy env variables
PACKAGE_MANAGER            // (default: 'npm')
AWS_ENVIRONMENT            // (default: '')
AWS_ENDPOINT               // (default: '')
CONFIG_FILE                // (default: '')
EVENT_SOURCE_FILE          // (default: '')
EXCLUDE_GLOBS              // (default: '')
AWS_ACCESS_KEY_ID          // (default: not set!)
AWS_SECRET_ACCESS_KEY      // (default: not set!)
AWS_PROFILE =              // (default: '')
AWS_SESSION_TOKEN =        // (default: '')
AWS_REGION =               // (default: 'us-east-1,us-west-2,eu-west-1')
AWS_FUNCTION_NAME          // (default: package.json.name or 'UnnamedFunction')
AWS_HANDLER                // (default: 'index.handler')
AWS_ROLE_ARN || AWS_ROLE   // (default: 'missing')
AWS_MEMORY_SIZE            // (default: 128)
AWS_TIMEOUT                // (default: 60)
AWS_RUN_TIMEOUT            // (default: 3)
AWS_ARCHITECTURE           // (default: 'x86_64')
AWS_DESCRIPTION            // (default: package.json.description or '')
AWS_RUNTIME                // (default: 'nodejs16.x')
AWS_PUBLISH                // (default: false)
AWS_FUNCTION_VERSION       // (default: '')
AWS_VPC_SUBNETS            // (default: '')
AWS_VPC_SECURITY_GROUPS    // (default: '')
AWS_TRACING_CONFIG         // (default: '')
AWS_LAYERS                 // (default: '')
AWS_LOGS_RETENTION_IN_DAYS // (default: '')
EVENT_FILE                 // (default: 'event.json')
PACKAGE_DIRECTORY          // (default: not set)
CONTEXT_FILE               // (default: 'context.json')
PREBUILT_DIRECTORY         // (default: '')
SRC_DIRECTORY              // (default: '')
DEPLOY_TIMEOUT             // (default: '120000')
DOCKER_IMAGE               // (default: '')
DEPLOY_ZIPFILE             // (default: '')
DEPLOY_USE_S3              // (default: false)
IMAGE_URI                  // (default: '')
AWS_DLQ_TARGET_ARN         // (default: not set)
AWS_TAGS                   // (default: '')

run

Runs your Amazon Lambda index.js file locally. Passes event.json data to the Amazon Lambda event object.

$ npx node-lambda@latest run --help
Usage: node-lambda run|execute [options]

Run your Amazon Lambda application locally

Options:
  -H, --handler [AWS_HANDLER]                                 Lambda Handler {index.handler} (default: "index.handler")
  -j, --eventFile [EVENT_FILE]                                Event JSON File (default: "event.json")
  -u, --runtime [AWS_RUNTIME]                                 Lambda Runtime (default: "nodejs16.x")
  -t, --timeout [AWS_RUN_TIMEOUT]                             Lambda Timeout (default: 3)
  -f, --configFile [CONFIG_FILE]                              Path to file holding secret environment variables (e.g. "deploy.env") (default: "")
  -x, --contextFile [CONTEXT_FILE]                            Context JSON File (default: "context.json")
  -M, --enableRunMultipleEvents [ENABLE_RUN_MULTIPLE_EVENTS]  Enable run multiple events (default: true)
  -y, --proxy [PROXY]                                         Proxy server (default: "")
  --apiGateway                                                Convert to API Gateway events (default: false)
  -h, --help                                                  display help for command

package

Bundles your application into a local zip file.

$ npx node-lambda@latest package --help
Usage: node-lambda package|zip [options]

Create zipped package for Amazon Lambda deployment

Options:
  --packageManager [PACKAGE_MANAGER]            Package manager used to install dependencies (default: "npm", options: "npm", "yarn")
  -A, --packageDirectory [PACKAGE_DIRECTORY]    Local Package Directory
  -I, --dockerImage [DOCKER_IMAGE]              Docker image for npm ci (default: "")
  -n, --functionName [AWS_FUNCTION_NAME]        Lambda FunctionName (default: "node-lambda")
  -H, --handler [AWS_HANDLER]                   Lambda Handler {index.handler} (default: "index.handler")
  -e, --environment [AWS_ENVIRONMENT]           Choose environment {dev, staging, production} (default: "")
  -x, --excludeGlobs [EXCLUDE_GLOBS]            Space-separated glob pattern(s) for additional exclude files (e.g.
                                                "event.json dotenv.sample") (default: "")
  -D, --prebuiltDirectory [PREBUILT_DIRECTORY]  Prebuilt directory (default: "")
  -m, --keepNodeModules [KEEP_NODE_MODULES]     Keep the current node_modules directory. (default: false)
  -v, --dockerVolumes [DOCKER_VOLUMES]          Additional docker volumes to mount. Each volume definition has to be
                                                separated by a space (e.g. "$HOME/.gitconfig:/etc/gitconfig
                                                $HOME/.ssh:/root/.ssh") (default: "")
  --no-optionalDependencies                     Run `npm install` with `--no-optional`
  -h, --help                                    display help for command

deploy

Bundles and deploys your application up to Amazon Lambda.

$ npx node-lambda@latest deploy --help
Usage: node-lambda deploy [options]

Deploy your application to Amazon Lambda

Options:
  --packageManager [PACKAGE_MANAGER]                    Package manager used to install dependencies (default: "npm", options: "npm", "yarn")
  -e, --environment [AWS_ENVIRONMENT]                   Choose environment {dev, staging, production} (default: "")
  -E, --endpoint [AWS_ENDPOINT]                         Choose endpoint (e.g. localstack, "http://127.0.0.1:4574") (default: "")
  -a, --accessKey [AWS_ACCESS_KEY_ID]                   AWS Access Key
  -s, --secretKey [AWS_SECRET_ACCESS_KEY]               AWS Secret Key
  -P, --profile [AWS_PROFILE]                           AWS Profile (default: "")
  -k, --sessionToken [AWS_SESSION_TOKEN]                AWS Session Token (default: "")
  -r, --region [AWS_REGION]                             AWS Region (default: "us-east-1,us-west-2,eu-west-1")
  -n, --functionName [AWS_FUNCTION_NAME]                Lambda FunctionName (default: "node-lambda")
  -H, --handler [AWS_HANDLER]                           Lambda Handler {index.handler} (default: "index.handler")
  -o, --role [AWS_ROLE]                                 Amazon Role ARN (default: "missing")
  -m, --memorySize [AWS_MEMORY_SIZE]                    Lambda Memory Size (default: 128)
  -t, --timeout [AWS_TIMEOUT]                           Lambda Timeout (default: 60)
  --architecture [AWS_ARCHITECTURE]                     The instruction set architecture that the function supports.  (x86_64|arm64) (default: "x86_64")
  -d, --description [AWS_DESCRIPTION]                   Lambda Description (default: "Command line tool for locally running and remotely deploying your node.js applications to Amazon Lambda.")
  -u, --runtime [AWS_RUNTIME]                           Lambda Runtime (default: "nodejs16.x")
  -p, --publish [AWS_PUBLISH]                           Lambda Publish (default: false)
  -L, --lambdaVersion [AWS_FUNCTION_VERSION]            Lambda Function Version (default: "")
  -b, --vpcSubnets [AWS_VPC_SUBNETS]                    Lambda Function VPC Subnet IDs (comma delimited) (default: "")
  -g, --vpcSecurityGroups [AWS_VPC_SECURITY_GROUPS]     Lambda VPC Security Group IDs (comma delimited) (default: "")
  -K, --kmsKeyArn [AWS_KMS_KEY_ARN]                     Lambda KMS Key ARN (default: "")
  -Q, --deadLetterConfigTargetArn [AWS_DLQ_TARGET_ARN]  Lambda DLQ resource
  -c, --tracingConfig [AWS_TRACING_CONFIG]              Lambda tracing settings (default: "")
  -l, --layers [AWS_LAYERS]                             Lambda Layers settings (e.g. "ARN1,ARN2[,..])" (default: "")
  -R, --retentionInDays [AWS_LOGS_RETENTION_IN_DAYS]    CloudWatchLogs retentionInDays settings (default: "")
  -G, --sourceDirectory [SRC_DIRECTORY]                 Path to lambda source Directory (e.g. "./some-lambda") (default: "")
  -I, --dockerImage [DOCKER_IMAGE]                      Docker image for npm ci (default: "")
  -f, --configFile [CONFIG_FILE]                        Path to file holding secret environment variables (e.g. "deploy.env") (default: "")
  -S, --eventSourceFile [EVENT_SOURCE_FILE]             Path to file holding event source mapping variables (e.g. "event_sources.json") (default: "")
  -x, --excludeGlobs [EXCLUDE_GLOBS]                    Space-separated glob pattern(s) for additional exclude files (e.g. "event.json dotenv.sample") (default: "")
  -D, --prebuiltDirectory [PREBUILT_DIRECTORY]          Prebuilt directory (default: "")
  -T, --deployTimeout [DEPLOY_TIMEOUT]                  Deploy Timeout (default: 120000)
  -z, --deployZipfile [DEPLOY_ZIPFILE]                  Deploy zipfile (default: "")
  -B, --deployUseS3 [DEPLOY_USE_S3]                     Use S3 to deploy. (default: false)
  -i, --imageUri [IMAGE_URI]                            URI of a container image in the Amazon ECR registry. (default: "")
  -y, --proxy [PROXY]                                   Proxy server (default: "")
  -A, --tags [AWS_TAGS]                                 Tags as key value pairs (e.g. "tagname1=tagvalue1,tagname2=tagvalue2)" (default: "")
  --silent                                              Silent  or  quiet mode (default: false)
  --no-optionalDependencies                             Run `npm install` with `--no-optional`
  -h, --help                                            display help for command

If you are deploying to a custom endpoint you may also need to pass in an access key/secret. For localstack these can be anything, but cannot be blank:

npx node-lambda@latest deploy --endpoint http://localhost:4574 --accessKey '1234' --secretKey '1234'

Custom Environment Variables

AWS Lambda will let you set environment variables for your function. Use the sample deploy.env file in combination with the --configFile flag to set values which will be added to the lambda configuration upon deploy. Environment variables will also be set when running locally using the same flag

Node.js Runtime Configuration

AWS Lambda now supports Node.js 18, Node.js 16 and Node.js 14. Please also check the Lambda runtimes page.

Use S3 to deploy

Use the command line argument --deployUseS3 or -B. (This option is true/false.) Example: % npx node-lambda@latest deploy -B

You can also set the environment variable DEPLOY_USE_S3. Example: DEPLOY_USE_S3=true

Use the environment variable to set the bucket name or S3 key prefix. The environment variable name is different for each region. Please set it to the environment variable you want to deploy. It can be set in .env.

Example:

# S3_<region>_BUCKET
S3_US_WEST_1_BUCKET=test_aaa

# S3_<region>_PREFIX
S3_US_WEST_1_PREFIX=bbb

In this case, the S3 key: test_aaa/bbb/deploy-package-${FunctionName}.zip

To deploy a container image to Lambda

  1. Pushing a Docker image to ECR
  2. Specify the Image URI of the ECR with the environment variable:IMAGE_URI or --imageUri option, and deploy.

Post install script

When running node-lambda deploy if you need to do some action after npm install --production and before deploying to AWS Lambda (e.g. replace some modules with precompiled ones or download some libraries, replace some config file depending on environment) you can create post_install.sh script. If the file exists the script will be executed (and output shown after execution) if not it is skipped. Environment string is passed to script as first parameter so you can use it if needed. Make sure that the script is executable.

Example post_install.sh:

printf "\n\n######  Post install script  ###### \n"
ENV="production";
if [ ! -z $1 ]
  then
    ENV=$1;
fi
cp -v "config_$ENV.js" "config.js" \
&& printf "######  DONE!  ###### \n\n"

Post invoke script (example)

If you wish to invoke your deployed AWS Lambda function, you can add the following as a script to your package.json:

"invoke:remote": "aws lambda invoke --function-name myLambdaFnName --payload fileb://fixtures/hi.json invoked.json --log-type Tail | jq -r '.LogResult' | base64 --decode && rm invoked.json"

Prebuilt packages

The --prebuiltDirectory flag is useful for working with Webpack for example. It skips npm install --production and post_install.sh and simply packages the specified directory.

Handling npm link and Dependencies With Local Paths

Perhaps the easiest way to handle these cases is to bundle the code using Webpack and use the --prebuiltDirectory flag to package the output for deployment.

ScheduleEvents

Optional Parameter

When using the eventSourceFile flag (-S or --eventSourceFile) to set a ScheduleEvent trigger, you can pass an optional ScheduleDescription key into the ScheduleEvent object with a custom description for the CloudWatch event rule you are defining. By default, node-lambda generates a ScheduleDescription for you based on the ScheduleName and ScheduleExpression of the rule.

Note on ScheduleState for ScheduleEvents

When setting ScheduleState to ENABLED or DISABLED for ScheduleEvents, it is useful to note that this sets the state of the CloudWatch Event rule but DOES NOT set the state of the trigger for the Lambda function you are deploying; ScheduleEvent triggers are enabled by default in the Lambda console when added using the eventSourceFile flag.

Known Issue

Duplicate ScheduleEvent Triggers

If you are adding a trigger via the eventSourceFile for the first time, remove preexisting triggers from the Lambda console before deploying. Deploying a Lambda with the --eventSourceFile flag will NOT overwrite the same triggers created from the AWS console and may result in a duplicate triggers for the same rule.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Coding style

This project uses JavaScript Standard Style.

JavaScript Style Guide

Running tests

$ npm install
$ npm test

More Repositories

1

dotenv

Loads environment variables from .env for nodejs projects.
JavaScript
17,736
star
2

dotenv-expand

Variable expansion for dotenv. Expand variables already on your machine for use in your .env file.
JavaScript
929
star
3

ansible-pi

Quickly setup your Raspberry Pi - particularly WIFI settings.
241
star
4

node-lambda-template

The bare minimum for a node.js app running on Amazon Lambda.
JavaScript
158
star
5

digitalocean

The easiest and most complete rubygem for DigitalOcean.
Ruby
153
star
6

disposable-email

Your own personal and hostable mailinator - using SendGrid's Inbound Webhook and Requestb.in
Go
38
star
7

sinatra-heroku-cedar-template

Sinatra Heroku Cedar Template - The bare minimum for a sinatra app on cedar, running thin, and using bundler.
Ruby
25
star
8

signature-mark

Draw on a canvas with a smooth signature.
JavaScript
21
star
9

writings

My writings - articles and things of that sort in version control.
Ruby
19
star
10

github-streaker

Reminds yourself to keep your GitHub streak going (with a friendly email reminder)
JavaScript
18
star
11

historysniff

JS script to deduce a visitors' browser history from a manifest file of websites.
JavaScript
14
star
12

kibble

RESTful API on top of Dogecoin. So endpnts.
JavaScript
12
star
13

signature-pad

Add a signing pad to your website or app.
JavaScript
11
star
14

phoneungap

python script for ungapping your phonegap application - to make ready for the app store
Python
9
star
15

retromail

Email as real mail delivered to your doorstep.
JavaScript
9
star
16

signature-js

The JavaScript that powers the front-end signing interface for Signature.io.
JavaScript
9
star
17

doc2pdf

Convert word documents to PDFs. Wrapper for doc2pdf.net.
Go
9
star
18

signature-api

API platform for signing documents.
Go
7
star
19

planningcenteronline-php-api-example

example of using planning center online's api with php
PHP
7
star
20

haraka-redis

Haraka plugin that will save an incoming email to a locally running redis server
JavaScript
6
star
21

ansible-dogecoind

Quickly get dogecoind running on your server using this ansible config
5
star
22

signature-signing

JavaScript library that renders the signature and text elements to the document.
JavaScript
5
star
23

numbers

Track leads by phone number. Smartly follow up with them X days later. Interface via SMS so it's all right on your phone.
JavaScript
5
star
24

flossedtoday

Flossed Today reminds you to floss with a daily email.
JavaScript
4
star
25

ec2-on-node

EC2 on NodeJS - Deploy a NodeJS app on EC2 in a few minutes.
JavaScript
4
star
26

carve-worker

Background worker for converting PDFs into an array of PNGs.
Go
4
star
27

merb_auth_slice_multisite

Used by investapp.com. Add multisite/subdomain functionality to your merb app as a slice - includes login form, remember me, and forgot password functionality.
Ruby
4
star
28

moviegrid

Python
4
star
29

signatureio-node

Node.js Bindings for Signature.io's API.
JavaScript
4
star
30

signatureio-ruby

Ruby Bindings for Signature.io's API.
Ruby
4
star
31

osc

Economic citizenship experiment aiming to increase economic participation in open source software.
Ruby
4
star
32

chucks

Making music with programming.
4
star
33

spitfiresky.com

webby source for Spitfire Sky (http://spitfiresky.com)
JavaScript
3
star
34

heroku-buildpack-mupdf

Heroku buildpack for MuPDF
Shell
3
star
35

gridracer

Control a RC car using Raspberry Pi and SendGrid.
JavaScript
3
star
36

carve-api

API to Convert PDFs into an array of PNGs.
Go
3
star
37

carve

Convert PDFs into an array of PNGs. Takes a url of a PDF and converts its pages into individual PNGs.
Go
3
star
38

mailtub

Ruby
3
star
39

codeday-static

Example code for using codeday-static
3
star
40

signature-catcher

Catches the webhook with the converted document arriving from signature-api.
Go
3
star
41

signature-document

JavaScript rendering engine for a signature-document.
JavaScript
3
star
42

sendgrid-php-batch-email

Example application showing how to send batch emails in PHP. Useful for when you want to send 1,000s of custom emails in one fell swoop.
PHP
3
star
43

sinatra_asset_packager

Opinionated asset packaging for Sinatra done well.
Ruby
2
star
44

arduino_with_javascript

use javascript and du.ino to control your Arduino
Arduino
2
star
45

timepicker.js

timepicker by Sam Collet and Anders Fajerson extended to handle refreshing position
JavaScript
2
star
46

paeasy

learning couchdb hosted apps through an accounting app
JavaScript
2
star
47

noob101

Websites for noobs!
TypeScript
2
star
48

carte

API of memory cards
Go
2
star
49

motdotla.github.io

Source code for mot.la
HTML
2
star
50

dotenv-eval

Add command substitution to dotenv
JavaScript
2
star
51

sendgrid-pusher-demo

Demo inspired by Kunal's color changing demo.
JavaScript
2
star
52

rails-graphql-heroku-template

The bare minimum for a Rails app implementing GraphQL, running puma, and hostable on Heroku (and elsewhere)
Ruby
2
star
53

signaturelogic

Logic for saving signature-api data to the database.
Go
2
star
54

signature-share

The shareable signing interface for signature-api.
Go
2
star
55

signatureio-node-personal

Signature.io Personal is an example app demonstrating the use of the Heroku Signature Add-On. See below to get started.
JavaScript
2
star
56

angrycorner

Organize the world's emotions (beginning with Anger) and make it universally accessible and useful.
Python
2
star
57

signature-fonticons

2
star
58

rails-on-docker

Get Ruby on Rails working with passenger and on Docker in a few minutes.
Ruby
2
star
59

sendgrid-apex

MOVED to: https://github.com/sendgrid/sendgrid-apex
Apex
2
star
60

zip-sendgrid-php-example

Send email from sendgrid-php zip
PHP
2
star
61

mottemuseum

Source code for father's museum website
JavaScript
2
star
62

sendgrid-webhook-then-send-inline-gmail

This little app is attempting to demonstrate how to send an email, then a robot (SendGrid) catches the email, and sends a reply back. That reply should be inline.
JavaScript
1
star
63

signature-chrome

The nav and chrome supporting a signature-document for signature.io
JavaScript
1
star
64

darylbusch.com

webby site for darylbusch.com
Ruby
1
star
65

bitcoinsms

Old crufty code. Reminded you of fluctuations in bitcoin price.
Ruby
1
star
66

bookvsmovie

Ruby
1
star
67

spring-attack

This is an example app for my session at the SpringOne2Gx.
CSS
1
star
68

abingoapart

Bingo game. Create at one of the An Event Apart conferences
Ruby
1
star
69

sendgrid-opensource-proposals

this document is a moving target and likely temporary. It's a tool to workout brining our open source libraries closer inline together.
1
star
70

oscnode

Economic citizenship experiment aiming to increase economic participation in open source software.
JavaScript
1
star
71

parsekit

Ruby
1
star
72

oceanmanager

I use ocean-manager to manage carve's servers on Digital Ocean. It automatically spins up servers and spins them back down.
Ruby
1
star
73

hapi-human-payload

Hapi plugin to lets your users send their payload as POST data or GET query parameters.
JavaScript
1
star
74

trilakeconsultants.com

webby site for trilakeconsultants.com
JavaScript
1
star
75

handshakejs-example-aprb

Handshakejs demo for Abril Ruby Conference
JavaScript
1
star
76

regular_form_submit_fix

get form submit fix for sammy.js
JavaScript
1
star
77

integration-example-vercel

▲💛 Vercel + Dotenv integration example
CSS
1
star
78

hello-nodejs-cloud66

JavaScript
1
star
79

ansible-role-dogecoind

1
star
80

jmading.com

webby site for jmading.com
JavaScript
1
star
81

human-first-example

Example app using a human first API approach.
JavaScript
1
star
82

riversidejs

JavaScript
1
star
83

riversideio-plugin

Embeddable script for accepting memberships for Riverside.io. Interfaces with victoria-club
JavaScript
1
star
84

simple_smart_scrollbar

CoffeeScript
1
star
85

retweeter

retweet from one twitter account to another automatically
Ruby
1
star
86

edwinmatthews.com

webby site for edwinmatthews.com
JavaScript
1
star
87

redisurlparser

Redis url parser is a go library for parsing redis://.. URLs into struct friendly options.
Go
1
star
88

westsidenannies.com

webby site for westsidenannies.com
JavaScript
1
star
89

people

example app demonstrated here: http://spitfiresky.com/blog/how-you-should-be-doing-testing-in-rails.html
Ruby
1
star
90

email-templates

1
star
91

srvdir-binary

Prebuilt heroku ready srvdir binary.
1
star
92

nodeployer

GitHub continous deployment to Amazon EC2. An alternative to Capistrano.
JavaScript
1
star
93

riversideruby

Ruby
1
star
94

visage-grid

JavaScript
1
star
95

spoofing_mac_address

1
star
96

go-by-example

Scripts created as I go through https://gobyexample.com/
Go
1
star
97

send-film-php

Receive a nightly email with a movie you can watch.
PHP
1
star
98

learning-java

Exercises I am accomplishing to learn Java
Java
1
star
99

goodfilms-graph

Get film data from Goodfil.ms.
JavaScript
1
star
100

wix

Rubygem to interact with Wix's add-on marketplace API.
Ruby
1
star