A tool to scaffold, deploy and update AWS Lambda functions from the command line.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
.gitignore
LICENSE Initial commit Aug 1, 2016
README.md Updated README with deploy configuration Sep 16, 2017
demo.gif Added padding to the gif Nov 24, 2016
logo.png
package-lock.json
package.json

README.md

Lambdasync logo

A tool to scaffold, deploy and update functions on AWS Lambda from the command line.

Demo

Installation

npm install lambdasync -g

Prerequisites

To use Lambdasync you will need an AWS Account, and credentials, check out the official docs on how to get your credentials before you start.

Getting started

To scaffold a new project run:

lambdasync new project-name

This will prompt you for all information needed to talk to the AWS APIs. See Prompt params for more information.

The new command will create a new folder with your project name containing.

A lambdasync.json that holds lambdasync meta data for your project.

A basic package.json file similar to what you would get from running npm init.

An index.js file that contains your handler function.

Handler functions

The handler function is what you actually deploy. lambdasync new has created a basic hello world type handler for you, that is ready to deploy:

'use strict';
exports.handler = (event, context, callback) => {
  callback(null, {
    statusCode: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify('Everything is awesome!')
  });
};

The handler function should always be in the ./index.js file and export a CommonJS module called handler like in the example.

The callback should always return an object with {statusCode, headers, body} like above.

More information on how to write a Lambda handler function can be found in the official docs.

Tutorial

A basic REST API handler function can be found in this tutorial, with example code here.

Express apps

If you are more familiar with writing express.js applications, and want to use that knowledge when writing lambda apps you can create your project with:

lambdasync new project-name --express

This will scaffold a project bootstrapped with aws-serverless-express, that lets you use most express goodness on Lambda.

Deploy

To deploy your API run:

lambdasync

inside your project folder.

Your project folder will be zipped and deployed to lambda, if this is the first deploy an API Gateway will be setup automatically to add an endpoint to your function.

When the deploy is done, you will get a URL where you can call your API.

Dev server

If you don't want to deploy to test every change you can use the built in dev server using:

lambdasync devserver

This will serve your handler function at http://localhost:3003 .

Adding secrets

lambdasync secret DB_HOST=127.0.0.1

Secrets can be stored to avoid putting sensitive data in your source code. Secrets are stored as AWS Lambda environment variables and can be accessed through process.env in your handler functions.

exports.handler = function(event, context, callback) {
  const {DB_HOST} = process.env.DB_HOST;
  // ... do something with DB_HOST
};

A secret can be removed with:

lambdasync secret remove DB_HOST

Note: Prior to 2.0 secrets were saved as API Gateway stage variables, because Lambda had no environment variable support.

Logging

Each request, and anything you log with console.log will be logged to AWS CloudWatch. If you don't want to have to login to the AWS console to see your logs you can use:

lambdasync logs

This will start outputting any new CloudWatch log events to your console.

Config

lambdasync config Will print out configuration info about your Lambda function, such as function ARN (Amazon Resource Name), Runtime (Node version), when the function was last modified, etc.

Lambdasync will also let you change the config for description, timeout and memory by running the config command with the key and new value:

lambdasync config timeout=3
lambdasync config memory=192
lambdasync config description='Example project for lambdasync'

Deploy configuration

Lambdasyncs goal is to provide as close to a "no config" experience, while still being a useful day to day tool for building serverless APIs. This is a hard line to walk, the most important thing is that the tool works out of the box with as little setup as possible, if you do find yourself wanting to change some Lambdasync behavior this is probably the section for you.

To configure Lambdasync you create a "lambdasync" JSON object in your package.json and add any of the following fields:

  • entry - The path to your entry/main file relative to the project root
  • include - An array of glob patterns* matching files that should be included in deploys to AWS Lambda
  • ignore - An array of glob patterns* matching files that should be ignored in deploys to AWS Lambda

Glob patterns are the node_modules/** or *.js you see in a lot of configuration and command line tools. Lambdasync supports any glob patterns compatible with minimatch where you can also find some more examples.

Example package.json:

{
  "name": "my-project",
  "version": "1.0.0",
  "lambdasync": {
    "entry": "dist/index.js",
    "ignore": ["dist/secrets/**"],
    "include": ["dist/**"]
  }
}

With this configuration only your dist/ directory will be deployed, and everything in it except the contents of your dist/secrets/ directory, and Lambda will be configured to look for the exported handler function in your dist/index.js file instead of the default index.js.

Calling AWS SDK methods

A hidden feature of lambdasync that is at least very useful during development for exploring the AWS SDK is the ability to call any AWS SDK method from the command line.

lambdasync -c AWSClass.methodName arg1=value1 arg2='value2 with spaces'

or to use a real, working example:

lambdasync -c Lambda.getFunction FunctionName=lambdaArn

If a value matches any key in the lambdasync.json file (like lambdaArn does) that value will be substituted with the value from the json file, otherwise it will be treated as text. If your value contains spaces add single quotes around it.

Prompt params

When setting up a new project lambdasync will prompt you for:

  • Profile name
  • AWS Credentials
  • Function name
  • AWS region

The profileName is used as an alias for your credentials that are saved in the ~/.aws directory in a format compatible with official AWS CLI profiles. That means no sensitive information is saved in the repository and you can reuse profiles between Lambdasync and AWS CLI.

How to get your access key and secret key is covered here.

If you only plan to use Lambdasync with one AWS account leave it at the default profile name: lambdasync. Otherwise having a work profile and a personal profile can be a good idea.

The function name will be automatically taken from the package.json, but you have a chance to change it.

AWS region will be saved to your profile as a default preference for future Lambdasync functions.