AWS Lambda Boilerplate

A TypeScript-first AWS Lambda boilerplate focused on build/test tooling, shared documentation, and a clean project baseline.

Overview

This repository is being positioned as an AWS Lambda boilerplate. Today it provides reusable TypeScript, Rollup, Jest, ESLint, Prettier, Docker, TypeDoc, and Serverless Framework scaffolding, while src/index.ts still contains placeholder exports that should be replaced or extended as Lambda-specific modules are introduced.

Included in This Boilerplate

• TypeScript project setup (tsconfig*.json)
• Rollup build pipeline for distributable outputs in lib/
• Jest test configuration with coverage output in dist/coverage
• ESLint + Prettier integration
• TypeDoc documentation generation to dist/docs
• Docker build verification via Dockerfile and docker-compose.yaml
• HonKit book generation to dist/book with custom dark theme
• Responsive landing page with glass-morphism design (nginx)
• Community standards files (Contributing, Code of Conduct, Security, Support)
• Changelog and release notes structure

Project Structure

src/                          Source files for Lambda handlers, utilities, and current placeholder exports
  index.ts                    Current entry point used by Rollup and TypeDoc
  handlers/direct-hello.ts    Sample direct-invocation Lambda handler for Serverless Framework
  handlers/hello.ts           Sample API Gateway Lambda handler
  handlers/scheduled.ts       Sample scheduled (EventBridge/cron) Lambda handler
events/                       Sample payloads for local invocation
  hello.invoke.json           Example event for direct invoke (`helloInvoke`)
  hello.apigw.json            Example API Gateway HTTP event for local invoke (`helloApi`)
serverless.yml                Serverless Framework deployment configuration
test/                         Jest test files (*.spec.ts)
docs/                         Documentation and release history
  styles/                     Custom CSS for HonKit book theme
  guide/deployments/          Deployment guides (quick-start and detailed)
  book.json                   HonKit configuration
  changes-log/                Per-date change logs
  release-notes/              Per-version release notes
CHANGELOG.md                  Top-level changelog
CONTRIBUTING.md               Contribution workflow
SECURITY.md                   Security policy
SUPPORT.md                    Support channels
docker/                       Docker assets for landing page and docs book
  nginx/                      Nginx configuration and landing page HTML
  docs.Dockerfile             Multi-stage build for docs site
  docker-compose.docs.yaml    Compose config for docs/book site

Quick Start

npm install
npm run build
npm run test:run

Available Scripts

• npm run build Build library artifacts via Rollup
• npm run test:run Run tests using Jest
• npm run test Run lint and tests
• npm run lint:run Run linter
• npm run lint:fix Run linter with auto-fix
• npm run build:docs Generate API documentation with TypeDoc
• npm run build:docs:book Build responsive HonKit book with dark theme
• npm run build:static Build static site artifacts into dist/ (index.html, book/, docs/, coverage/)
• npm run serverless:print Print the resolved Serverless Framework configuration
• npm run serverless:package Build and package the Lambda service into .serverless/
• npm run serverless:invoke:local Build and invoke the direct function locally with events/hello.invoke.json
• npm run serverless:invoke:local:api Build and invoke the API Gateway function locally with events/hello.apigw.json
• npm run serverless:deploy Build and deploy the sample function
• npm run serverless:deploy:function Update only the deployed sample function code
• npm run serverless:remove Remove the deployed Serverless stack

Current Status

• src/index.ts still exposes placeholder LibraryMetadata/HealthStatus types and helper functions from the original scaffold.
• serverless.yml now deploys a directly invokable sample function and a scheduled cron function without requiring API Gateway.
• src/handlers/direct-hello.ts provides the default Serverless Framework direct-invocation function.
• src/handlers/scheduled.ts provides a sample function triggered by an EventBridge schedule rule.
• src/handlers/hello.ts now provides a typed sample API Gateway handler using @types/aws-lambda.
• No AWS SDK runtime dependency has been added yet.
• The repository is ready for Lambda-specific implementation work, but event sources beyond direct invocation still need to be introduced explicitly.

Serverless Framework Deployment

The repository includes serverless.yml with two deployed functions by default:

Function key	Handler	Event source
helloInvoke	directHelloHandler	None (direct invocation only)
scheduledCron	scheduledHandler	EventBridge rule — rate(5 minutes)
helloApi	helloHandler	API Gateway HTTP API — GET /hello, GET /hello/{name}

Typical workflow:

npm run serverless:package
npm run serverless:invoke:local
npm run serverless:deploy

Serverless Framework v4 requires login (serverless login) or a license key before running deployment commands.

After the first deployment, you can update only the function code with:

npm run serverless:deploy:function

To delete the stack:

npm run serverless:remove

Sample Lambda Functions

Direct invocation sample

The default Serverless Framework function is directHelloHandler, a simple Lambda example that:

• reads name from the invocation payload
• falls back to world when no name is provided
• returns a JSON object with a greeting, request id, timestamp, and resolved input source

Example usage in serverless.yml is already wired to the built export:

functions:
  helloInvoke:
    handler: lib/index.min.directHelloHandler

Example event payload:

{
  "name": "Bayu"
}

Example direct invocation response:

{
  "message": "Hello, Bayu!",
  "requestId": "request-direct-123",
  "timestamp": "2026-05-12T00:00:00.000Z",
  "input": {
    "name": "Bayu",
    "source": "event"
  }
}

Scheduled cron sample

scheduledHandler is triggered by an EventBridge scheduled rule. It receives the raw ScheduledEvent envelope and returns a structured log-friendly result:

{
  "status": "ok",
  "executedAt": "2026-05-12T08:00:00.000Z",
  "requestId": "…",
  "source": "aws.events",
  "account": "123456789012",
  "region": "ap-southeast-1"
}

The default schedule in serverless.yml is rate(5 minutes). To change it to a specific cron expression:

events:
  - schedule:
      rate: cron(0 8 * * ? *)   # every day at 08:00 UTC
      enabled: true

API Gateway sample

The boilerplate now includes helloHandler, a simple API Gateway HTTP API example that:

• reads name from pathParameters.name or queryStringParameters.name
• falls back to world when no name is provided
• returns a JSON response with a greeting, request id, timestamp, and the resolved input source

Example routes:

• GET /hello
• GET /hello?name=Bayu
• GET /hello/Bayu

Example usage:

import { helloHandler } from '@bayudwiyansatria/aws-lambda-boilerplate'

export const handler = helloHandler

Example response body:

{
  "message": "Hello, Bayu!",
  "requestId": "request-123",
  "timestamp": "2026-05-12T00:00:00.000Z",
  "input": {
    "name": "Bayu",
    "source": "query"
  }
}

How to Use This Boilerplate

1. Replace or extend the placeholder exports in src/index.ts with Lambda-focused modules.
2. Add tests in test/ using the existing *.spec.ts Jest pattern.
3. Extend serverless.yml with additional functions or event sources when the target deployment approach is chosen.
4. Update README and docs with concrete handler, event, and deployment examples as they are added.
5. Keep changelog and release notes updated for each release.

Documentation

• Docs Home
• Deployment Quick Start — Quick reference for all invocation modes
• Deployment & Invocation Guide — Comprehensive deployment guide with examples
• Summary
• Latest Release Notes
• Initial Changes Log

Documentation & Docs Site

The boilerplate includes a complete documentation site built with TypeDoc and HonKit:

• API Docs: TypeDoc-generated reference available at dist/docs/ on deployment
• Developer Book: HonKit-powered structured guide at dist/book/ with dark theme, responsive design, and full-text search
• Landing Page: Responsive HTML welcome page with links to docs, coverage, and book — accessible via Docker at localhost:8080 when running the docs container

View Docs Locally

Build both TypeDoc and HonKit:

npm run build:docs
npm run build:docs:book

Docker Docs Site

To serve the docs site with landing page, coverage, and book via Docker:

docker compose -f docker/docker-compose.docs.yaml up

Then visit http://localhost:8080 to see the landing page with links to:

• Documentation — Full TypeDoc API reference
• Coverage Report — Test coverage HTML report from Jest
• Developer Book — Structured guides with dark theme and responsive layout

Contributing and Governance

• Contributing Guide
• Code of Conduct
• Security Policy
• Support Guide

Authors

• Bayu Dwiyan Satria - Creator and Maintainer

Acknowledgments

Thanks to the open-source community and all contributors for support and inspiration.

License

MIT. See LICENSE.