es2017-lambda-boilerplate

Note: As of April 2018, AWS has announced support for Lambda functions on Node.js 8.10, which already supports all ES2018-2016 features added by this boilerplate (and more). You can however, still use this boilerplate on Node.js 8.10 to make use of the unit testing features.

This is a boilerplate for AWS Lambda Node.js 6.10.0 functions, which allows you to use the latest JavaScript ES2016, ES2017 and ES2018 features. The boilerplate also allows you to test your function in a Docker container (thanks to docker-lambda), and also includes common configurations for CI/CD, for both Travis CI and AWS CodeBuild + AWS CloudFormation.

Latest JavaScript features

This boilerplate adds support for the following most commonly used JavaScript features that are not natively supported on Node.js 6.10:

Note: Most ES2015/ES6 are earlier features are supported.

Usage

Edit your Lambda function under src/main.js, and run:

npm run build

This will transpile your functions down to ES5 using Babel, so that it can be executed using the Node.js 6.10.0 runtime.

For convenience, the following command will create an artifact.zip file which you can upload to AWS Lambda:

npm run package

Testing

You can run automated tests for your Lambda function inside of a Docker container using docker-lambda:

npm run test

All files in the test/ directory which end with .test.js will be interpreted as a test suite. A sample unit test is provided under test/example.test.js to get you started.

The test runner used is Jest (with Jasmine). Using docker-lambda also requires Docker to be installed on your host; see the docs for docker-lambda for more instructions.

Specification tests

In order to ensure that the Babel configuration works and is following the spec, the boilerplate also runs several automated tests to catch any Babel misconfigurations.

• Functional testing: Runs the relevant spec tests from Test262 (actual tests taken from node.green) on docker-lambda to mock the AWS Lambda environment
• Snapshot testing: Unit testing strategy by storing snapshots of Babel-transformed source code and running unit tests against them

You can find the spec tests under spec/functional and spec/snapshot respectively.

If you are not going to modify .babelrc, you can choose to skip these tests by omitting the npm run spec script in .travis.yml. This will help to speed up your builds by a bit.

Deployment

Deployment using the AWS SDK

You can automatically deploy to AWS Lambda locally or through CI (e.g. Travis CI) using the AWS SDK, as long as you provide an access key for an IAM user that has write access to AWS Lambda. A single NPM script allows you to deploy using this method:

npm run deploy

See Environment variables for the list of environment variables that are required for SDK deployment.

Deployment through CloudFormation + CodeBuild

Instead of depending on external tools like Travis CI, you can also choose to use AWS CloudFormation to bootstrap the relevant AWS resources, integrated with AWS CodeBuild and AWS CodePipeline. Alternatively, deployment via AWS CodeStar may also be supported out of the box.

To modify the build process, you can update the CodeBuild configuration file at buildspec.yml. To modify the properties of the resultant Lambda function, you can update the CloudFormation configuration file at samTemplate.yml.

If you are new to AWS CI/CD tools, you can follow the official AWS tutorial to set up a build pipeline using CodePipeline. Take note of the following:

• Set up a S3 bucket for uploading CodeBuild artifacts to.
  • If the CodeBuild build fails, you may need to set the S3_BUCKET environment variable within CodeBuild directly.
• Ensure that the IAM roles have the necessary permissions to access required resources, including the S3 bucket.
• The CloudFormation template filename under CodePipeline settings should be template.yml.

Using the AWS SDK

You can write Lambda functions that make use of the AWS SDK by simply import-ing aws-sdk. The package is installed globally within the AWS Lambda environment, so you don't need to add it to your package.json.

Also make sure that your function has Internet connectivity (i.e. not within a VPC without a NAT gateway). The internetConnectivityTest.js utility is included to help to debug such problems early when deploying to AWS Lambda.

Environment variables

If you plan to use the AWS SDK, either for deployment (using npm run deploy), or within your function itself, you need to pass the following environment variables:

• AWS_ACCESS_KEY_ID: IAM user access key ID
• AWS_SECRET_ACCESS_KEY: IAM user secret access key
• AWS_REGION: AWS region where the Lambda function resides in (required for SDK deployment only)
• LAMBDA_FUNCTION_NAME: Name or ARN of the Lambda function (required for SDK deployment only)

This will work if you store it in a .env file in the root of the project (see dotenv), or if you define it within Travis CI itself (see Travis CI docs).

IAM user permissions

The minimum permissions required for the IAM user for SDK deployment are:

• lambda:UpdateFunctionCode

Remember to add more permissions as required if you need to access the SDK in your function.

Why?

Reduce callback hell with async/await

The highest version of Node.js supported on AWS Lambda is 6.10.0, which supports only features up to ES2015/ES6. Newer features in ES2017, such as async/await, are incredibly useful when performing network requests, such as when used with the AWS SDK:

const EC2 = new AWS.EC2();
const Route53 = new AWS.Route53();

// Get instance by ID.
const instances = await EC2.describeInstances({ InstanceIds: 'i-abcdef01' }).promise();

// Get public IP address.
const publicIpAddress = instances.Reservations[0].Instances[0].PublicIpAddress;

// Do something else with the IP address...
await Route53.changeResourceRecordSets({
    // ...
}).promise();

Run automated tests locally/through CI

Instead of testing your Lambda function by uploading to AWS Lambda every single time, running automated tests in conjunction with CI is a better option. By using Docker to mock the AWS Lambda environment locally, you can write test cases to verify the correctness of your function, given an input (the Lambda event):

import run from './util/runner';

it('should work', function() {
    // Sample event from SNS.
    const event = {
        Records: [
            {
                EventVersion: '1.0',
                EventSource: 'aws:sns',
                Sns: {
                    MessageId: '95df01b4-ee98-5cb9-9903-4c221d41eb5e',
                    Message: 'Hello from SNS!',
                    ...
                },
            },
        ],
    };

    // Run the Lambda function against this event.
    const result = run(event);

    expect(result).toEqual(true);
});

This strategy also does not utilise your AWS Lambda invocation credits - meaning you are free to run as many tests as often as you like!

Acknowledgements

This boilerplate was first inspired from this post by Jesse Cascio.

License

MIT