Working with Serverless Framework

This guide explains how to use Serverless Framework to deploy and manage AWS Lambda functions in this boilerplate.

Overview

Serverless Framework is an open-source CLI that simplifies Lambda deployment by translating serverless.yml into CloudFormation templates. It handles infrastructure as code, environment management, and function updates.

Prerequisites

  1. Install Serverless Framework CLI globally:

    npm install -g serverless

  2. Verify installation:

    serverless --version

  3. Configure AWS credentials:

    aws configure

    Or set environment variables:

    export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_DEFAULT_REGION=ap-southeast-1

Project Structure

The boilerplate uses serverless.yml to define three Lambda functions:

service: aws-lambda-boilerplate
provider:
  name: aws
  runtime: nodejs20.x
  stage: ${opt:stage, 'dev'}
  region: ${opt:region, 'ap-southeast-1'}

functions:
  helloApi:          # API Gateway HTTP API function
  helloInvoke:       # Direct invocation function
  scheduledCron:     # EventBridge scheduled function

Common Workflows

1. Initial Deployment

Deploy all three functions to AWS:

npm run serverless:deploy

Or:

serverless deploy

Output includes:

  • API Gateway endpoint URL
  • Lambda function ARNs
  • IAM role ARN

2. Deploy Only One Function

After initial deployment, update a single function without redeploying infrastructure:

npm run serverless:deploy:function -- --function helloApi
npm run serverless:deploy:function -- --function helloInvoke
npm run serverless:deploy:function -- --function scheduledCron

3. Deploy to Different Stage/Region

Deploy to production in a different region:

npm run serverless:deploy -- --stage prod --region ap-southeast-1

Function names will include the stage: aws-lambda-boilerplate-prod-helloApi

4. View Configuration

Print the resolved Serverless configuration:

npm run serverless:print

Or see just the functions:

serverless info

5. Local Invocation

Test functions locally without deploying:

# Test direct invoke
npm run serverless:invoke:local

# Test API Gateway
npm run serverless:invoke:local:api

# Invoke a specific function
serverless invoke local --function helloInvoke --data '{"name":"Test"}'

6. Remove Stack

Delete all deployed resources:

npm run serverless:remove

Warning: This deletes:

  • Lambda functions
  • API Gateway
  • EventBridge rules
  • IAM roles
  • CloudWatch log groups

Environment Variables and Secrets

Stage-Specific Configuration

Use serverless.yml parameters for stage-specific secrets:

provider:
  environment:
    STAGE: ${sls:stage}
    REGION: ${aws:region}
    LOG_LEVEL: ${env:LOG_LEVEL, 'info'}

functions:
  helloApi:
    environment:
      API_KEY: ${ssm:/api/key/${sls:stage}}  # AWS Systems Manager Parameter

Accessing in Lambda Code

const stage = process.env.STAGE;
const apiKey = process.env.API_KEY;

Managing Logs

View Live Logs

Stream logs from all functions:

serverless logs --function helloApi --tail
serverless logs --function scheduledCron --tail

View CloudWatch Logs

# List log streams
aws logs describe-log-streams \
  --log-group-name /aws/lambda/aws-lambda-boilerplate-dev-helloApi

# Tail logs
aws logs tail /aws/lambda/aws-lambda-boilerplate-dev-helloApi --follow

Custom Commands

Add custom commands to serverless.yml:

custom:
  myVar: hello-world

functions:
  myFunction:
    handler: lib/index.min.myHandler
    environment:
      MY_VAR: ${self:custom.myVar}

Tips & Best Practices

1. Build Before Deploy

Always build the TypeScript/Rollup bundle before deploying:

npm run build && npm run serverless:deploy

Or create a pre-deploy hook in serverless.yml:

plugins:
  - serverless-plugin-typescript

2. Use Stages Wisely

  • dev — local/development deployments (short-lived)
  • staging — pre-production testing
  • prod — production (enable X-Ray tracing, CloudWatch alarms)
npm run serverless:deploy -- --stage prod

3. Monitor Costs

Keep function memory small (128 MB is typical for simple handlers):

functions:
  helloApi:
    memorySize: 128
    timeout: 6

4. Version Control for serverless.yml

Track serverless.yml in Git, but not AWS credentials:

# .gitignore
.env
.serverless/
node_modules/

5. IAM Permissions

Ensure your AWS user/role has minimal required permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:*",
        "apigateway:*",
        "events:*",
        "iam:*",
        "logs:*",
        "cloudformation:*"
      ],
      "Resource": "*"
    }
  ]
}

Troubleshooting

"Credentials not found"

aws configure
# or
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

"InvalidParameterValueException: Code SHA256 does not match"

Build the code before deploying:

npm run build
npm run serverless:deploy

"Permission Denied" Creating Role

Your AWS user needs iam:* permissions. Ask your account administrator.

Function times out during deploy

Increase the deployment timeout in serverless.yml:

provider:
  timeout: 30  # 30 seconds

Advanced: Custom Plugins

Add community plugins for extended functionality:

npm install --save-dev serverless-plugin-warmup

Then in serverless.yml:

plugins:
  - serverless-plugin-warmup

functions:
  helloApi:
    warmup: true  # Keep function warm

results matching ""

    No results matching ""