@nypl/node-lambda-boilerplate
v1.0.0
Published
An AWS node-lambda boilerplate written in ES7 via Babel that includes various configuration, testing, and deployment scripts
Downloads
1
Readme
Node Lambda Boilerplate
A boilerplate (starter kit) for writing AWS Lambdas in Node using the node-lambda module. Supports ES7 syntax via babel and contains pre-configured NPM scripts found in package.json
that enable you to run your lambda locally, test your code, package and deploy your lambda to AWS based of your aws-profile
.
Table of Contents
- Requirements
- Getting Started
- Dependencies
Version
v1.0.0
Requirements
Written in ES7 AWS Node Target - Node 6.10.3
Features
- Pre-built NPM scripts to setup configuration files, run the lambda locally and deploy to the appropriate AWS profile environments
- Supports ES7 syntax via Babel transpilation
- Unit tests scaffolding and examples are setup in
./test
- Contains full test coverage integration via Mocha & Istanbul
- Supports TravisCI for running test and is setup to add CI
- All code is linted via StandardJS
- Contains helper methods used repeatedly across services (OAuth/Caching)
- Integrates Logging and conforms to NYPL Standards
- Integrates KMS decryption when
NODE_ENV
is set toproduction
for AWS environments - Contains custom ErrorHelper that is customizable for better error tracing
Getting Started
Installation
Install all Node dependencies via NPM
$ npm install
Setup Configurations
Once all dependencies are installed, you want to run the following NPM commands included in the package.json
configuration file to setup a local development environment.
Step 1: Create an .env
file for the node-lambda
module
Copies the sample .env file under ./sample/.env.sample into ./.env
$ npm run setup:node-lambda-env
Step 2: Add your AWS environment variables
Once the .env
file is copied, open the file and edit the following marked required:
AWS_REGION=us-east-1
AWS_FUNCTION_NAME=<FUNCTION NAME> (required in UpperCamelCase)
AWS_MEMORY_SIZE=128 (required)
AWS_TIMEOUT=30 (required)
AWS_DESCRIPTION=
AWS_RUNTIME=nodejs6.10 (set as default)
AWS_VPC_SUBNETS=
AWS_VPC_SECURITY_GROUPS=
AWS_TRACING_CONFIG=
EXCLUDE_GLOBS="event.json"
PACKAGE_DIRECTORY=build
Note: This ENV file is used by node-lambda to obtain your AWS basic configuration. AWS ARN_ROLE and PROFILES are handled by npm commands via --profile and --role
Step 3: Setup your environment specific {environment}.env
file
Running the following NPM Commands will:
- Set up your LOCAL
.env
file as./config/local.env
used for local development
$ npm run setup:local-env // Used in local development when running `npm run local-run`
- Set up your DEVELOPMENT
.env
file as./config/development.env
$ npm run setup:development-env
- Set up your PRODUCTION
.env
file as./config/production.env
$ npm run setup:production-env
These environment specific .env
files will be used to set environment variables when deployed by the node-lambda
module.
An example of the sample deployment environment *.env
file:
OAUTH_PROVIDER_URL=XXX
OAUTH_PROVIDER_SCOPE=XXX
OAUTH_CLIENT_ID=XXX
OAUTH_CLIENT_SECRET=XXX
NODE_ENV=XXX // Use 'development' when developing locally via `npm run local-run`. If deploying to AWS use 'production', this will trigger the decryption client.
Step 4: Setup your environment specific event_sources_{environment}.json
file
This file is used by the node-lambda
module to deploy your Lambda with the correct mappings.
You must edit the file once created and add your specific EventSourceArn value, found in the AWS Console. If no mapping is necessary, update the file to an empty object {}
.
Running the following NPM Commands will:
- Set up your DEVELOPMENT
event_sources_development.json
file in./config/
$ npm run setup:development-sources
- Set up your PRODUCTION
event_sources_production.json
file in./config/
$ npm run setup:production-sources
Developing Locally
To develop and run your Lambda locally you must ensure to complete Step 1
and Step 2
of the Setup process.
REMINDER: Your ./config/local.env
and ./.env
environment variables MUST be configured in order for the next step to work.
Next, run the following NPM command to use the sample event found in ./sample/sample_event.json
.
Exceutes
node lambda run
pointing the the sample event.
$ npm run local-run // Code is transpiled into dist/ and node-lambda will use that as the target path
Deploying your Lambda
To deploy your Lambda function via the node-lambda
module ensure you have completed all the steps of the Setup process and have added all configuration variables required.
The following NPM Commands will execute the node-lambda deploy
command mapping configurations to the proper environments (qa & production). These commands can be modified in package.json
.
Prior to the execution of any
npm deploy ...
commands,npm run build
is executed to successfully transpile all ES7 code th Node 6.10.x
- Runs
node-lambda deploy
with DEVELOPMENT configurations
$ npm run deploy:development
- Runs
node-lambda deploy
with PRODUCTION configurations
$ npm run deploy:production
Tests
Test Coverage
Istanbul is currently used in conjunction with Mocha to report coverage of all unit tests.
Simply run:
$ npm run coverage:report
Executing this NPM command will create a ./coverage/
folder with an interactive UI reporting the coverage analysis, now you can open up ./coverage/index.html
in your browser to view an enhanced report.
Running Unit Tests
Unit tests are written using Mocha, Chai and Sinon. All tests can be found under the ./test
directory. Mocha configurations are set and can be modified in ./test/mocha.opts
.
To run test, use the following NPM script found in
package.json
.
$ npm run test // Will run all tests found in the ./test/ path, for excluded files see nyc->exclude in package.json
$ npm run test [filename].test.js // Will run a specific test for the given filename
Linting
This codebase currently uses Standard JS as the JavaScript linter.
To lint files use the following NPM command:
$ npm run lint // Will lint all files except those listed in package.json under standard->ignore
$ npm run lint [filename].js // Will lint the specific JS file