typescript

Typescript Serverless Boilerplate

Typescript boilerplate AWS Lambda service which is invoked via API Gateway.

Contents

1. Installation / Setup
2. Local Development
3. Testing
4. Encrypting Secrets
5. Deployment
   1. Staging
   2. Prerelease
   3. Production

Installation / Setup

yarn install

Local Development

Best practice is to develop locally using a TDD approach. The boilerplate includes sample tests on which you can build, including example of how to mock AWS services.

Start the development environment with:

yarn dev

Try out the webhook with curl:

curl -s \
  -X POST \
  -H "content-type: application/json" \
  -d '{"id":"s1d2f34","foo":"bar"}' \
  http://localhost:3000/webhook | \
  jq

Testing

yarn test

or

yarn watch:test

Encrypting Secrets

In production, encrypt sensitive environment variables or other secret strings with KMS:

yarn encrypt-string "super secret string"

To decrypt cyphertext, use the kmsDecrypt() utility in ~/src/utils/kms.ts. Base64 encoded strings passed to kmsDecrypt() will get decrypted while strings which are not base64 encoded (and therefore likely not encrypted) will simply be returned as-is from kmsDecrypt(). kmsDecrypt() also accepts an array of strings, which are decrypted in parallel. To improve performance across Lambda invocations, decrypted strings are cached for you. To decrypt cyphertext, in your code:

import handler from 'alagarr'
import kmsDecrypt from './utils/kms'

if (FOR_EXAMPLE_IN_DEVELOPMENT) {
  const SUPER_SECRET = 'super secret string, unencrypted'
} else if (FOR_EXAMPLE_IN_PRODUCTION) {
  const SUPER_SECRET = 'AQECAHj6Y8swFFZ8sg2A5LDTngYQ4IY...YtXTBbxtG0Z0wAQG7HuQ=='
}

export default handler(async (request: any, response: any) => {
  const SUPER_SECRET_DECRYPTED = await kmsDecrypt(SUPER_SECRET) // result gets cached :-)
  const { body } = request

  // Do something useful with SUPER_SECRET_DECRYPTED,
  // ...like connect to a database

  return response.json({ message: 'Hi.', body })
})

To deploy secrets as part of an environment variable, add it to serverless.yml like so:

service:
  name: ${self:custom.package.name}
  awsKmsKeyArn: ${self:custom.package.config.awsKmsKeyArn} # use a custom kms key, defined in package.json

provider:
  name: aws
  environment:
    SUPER_SECRET: AQECAHj6Y8swFFZ8sg2A5LDTngYQ4IY...YtXTBbxtG0Z0wAQG7HuQ==

Deployment

Staging

yarn deploy

Prerelease

npm version prerelease

Production

npm version [major|minor|patch]