serverless-aws-node-starter

Modern AWS Serverless Starter Kit built on top of the Serverless Framework, giving you support for:

• JavaScript linting with ESLint and style guide created by Airbnb
• Unit tests with Jest
• GIT commit with Commitizen
• GIT hooks with husky to lint code on every commit and run tests before push
• Local development with serverless-offline
• Releases with semantic-release
• CI/CD with Drone.io
• API documentation with Swagger UI

Requirements

• Node.js v8.10.0
• Serverless Framework
• AWS CLI account configured
• Docker - for API documentation

Install

# If you don't already have the serverless cli installed, do that
npm install -g serverless

# Use the serverless cli to install this repo
serverless install --url https://github.com/dczepierga/serverless-aws-node-starter --name <your-service-name>

# cd into project and set it up
cd <your-service-name>

# Install dependencies
npm install

Now you only need to change service name in following files:

• package.json - name field
• serverless.yml - service field

Deploy

If you've already set up your default AWS credentials:

npm run deploy

By default script will deploy to dev stage and eu-west-1 region. You can deploy to different stage or region by passing command line arguments:

npm run deploy -- --stage test --region us-east-1

Development

Local dev server - simulate API Gateway

npm start

By default local dev server will use dev stage and eu-west-1 region. You can start local dev server for different stage or region by passing command line arguments:

npm start -- --stage test --region us-east-1

For more options check serverless-offline plugin documentation - Usage and command line options

Creating and deploying new functions

Create function with unit tests

The starter Hello World function can be found at ./src/handler.js with unit tests './src/handler.js`. There you can find a basic function that returns success response with body and simple unit test for this functionality.

This is all basic Serverless. If you've never used it, be sure to get familiar with their docs. More information about writing unit tests using Jest can be found in their guide.

Create configuration

The starter Hello World configuration can be found at src/handler.yml and at serverless.yml in the functions section (linked file).

More details about function configuration can be found in the AWS functions guide

IMPORTANT Remember to add all required files in package/include section. Without this your function may not work after deploy to the cloud!

Test and diagnose your function

You can run unit tests using following command:

npm test

More options is available in Jest docs - CLI Options.

If you want to diagnose you function and local dev webserver is not enough for you, then you can invoke the function with logs - more details you can find in the Serverless docs - AWS Invoke.

Commit your code

Add all files to stage and run:

npm run commit

You'll be prompted to fill out any required commit fields at commit time.

API documentation

Documentation for AWS API Gateway is provided by serverless-aws-documentation plugin and exported to Swagger UI format.

To open deployed to AWS API Gateway documentation in Swagger UI, you must run:

npm run docs

Cleanup

npm run detroy

By default script will cleanup dev stage and eu-west-1 region. You can cleanup different stage or region by passing command line arguments:

npm run detroy -- --stage test --region us-east-1