Patterns for creating high-performance AWS Lambda functions in TypeScript with optimized cold starts.
Overview
This skill provides complete patterns for AWS Lambda TypeScript development, covering two main approaches:
NestJS Framework
- Full-featured framework with dependency injection, modular architecture, and extensive ecosystem
Raw TypeScript
- Minimal overhead approach with maximum control and smaller bundle size
Both approaches support API Gateway and ALB integration with production-ready configurations.
When to Use
Use this skill when:
Creating new Lambda functions in TypeScript
Migrating existing TypeScript applications to Lambda
Optimizing cold start performance for TypeScript Lambda
Choosing between framework-based and minimal TypeScript approaches
Configuring API Gateway or ALB integration
Setting up deployment pipelines for TypeScript Lambda
Instructions
1. Choose Your Approach
Approach
Cold Start
Bundle Size
Best For
Complexity
NestJS
< 500ms
Larger (100KB+)
Complex APIs, enterprise apps, DI needed
Medium
Raw TypeScript
< 100ms
Smaller (< 50KB)
Simple handlers, microservices, minimal deps
Low
2. Project Structure
NestJS Structure
my-nestjs-lambda/
├── src/
│ ├── app.module.ts
│ ├── main.ts
│ ├── lambda.ts # Lambda entry point
│ └── modules/
│ └── api/
├── package.json
├── tsconfig.json
└── serverless.yml
Raw TypeScript Structure
my-ts-lambda/
├── src/
│ ├── handlers/
│ │ └── api.handler.ts
│ ├── services/
│ └── utils/
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
└── template.yaml
3. Implementation Examples
See the
References
section for detailed implementation guides. Quick examples:
NestJS Handler:
// lambda.ts
import
{
NestFactory
}
from
'@nestjs/core'
;
import
{
ExpressAdapter
}
from
'@nestjs/platform-express'
;
import
serverlessExpress
from
'@codegenie/serverless-express'
;
import
{
Context
,
Handler
}
from
'aws-lambda'
;
import
express
from
'express'
;
import
{
AppModule
}
from
'./src/app.module'
;
let
cachedServer
:
Handler
;
async
function
bootstrap
(
)
:
Promise
<
Handler
>
{
const
expressApp
=
express
(
)
;
const
adapter
=
new
ExpressAdapter
(
expressApp
)
;
const
nestApp
=
await
NestFactory
.
create
(
AppModule
,
adapter
)
;
await
nestApp
.
init
(
)
;
return
serverlessExpress
(
{
app
:
expressApp
}
)
;
}
export
const
handler
:
Handler
=
async
(
event
:
any
,
context
:
Context
)
=>
{
if
(
!
cachedServer
)
{
cachedServer
=
await
bootstrap
(
)
;
}
return
cachedServer
(
event
,
context
)
;
}
;
Raw TypeScript Handler:
// src/handlers/api.handler.ts
import
{
APIGatewayProxyEvent
,
APIGatewayProxyResult
,
Context
}
from
'aws-lambda'
;
export
const
handler
=
async
(
event
:
APIGatewayProxyEvent
,
context
:
Context
)
:
Promise
<
APIGatewayProxyResult
>
=>
{
return
{
statusCode
:
200
,
headers
:
{
'Content-Type'
:
'application/json'
}
,
body
:
JSON
.
stringify
(
{
message
:
'Hello from TypeScript Lambda!'
}
)
}
;
}
;
Core Concepts
Cold Start Optimization
TypeScript cold start depends on bundle size and initialization code. Key strategies:
Lazy Loading
- Defer heavy imports until needed
Tree Shaking
- Remove unused code from bundle
Minification
- Use esbuild or terser for smaller bundles
Instance Caching
- Cache initialized services between invocations
See
Raw TypeScript Lambda
for detailed patterns.
Connection Management
Create clients at module level and reuse:
// GOOD: Initialize once, reuse across invocations
import
{
DynamoDBClient
}
from
'@aws-sdk/client-dynamodb'
;
const
dynamoClient
=
new
DynamoDBClient
(
{
region
:
process
.
env
.
AWS_REGION
}
)
;
export
const
handler
=
async
(
event
:
APIGatewayProxyEvent
)
=>
{
// Use dynamoClient - already initialized
}
;
Environment Configuration
// src/config/env.config.ts
export
const
env
=
{
region
:
process
.
env
.
AWS_REGION
||
'us-east-1'
,
tableName
:
process
.
env
.
TABLE_NAME
||
''
,
debug
:
process
.
env
.
DEBUG
===
'true'
,
}
;
// Validate required variables
if
(
!
env
.
tableName
)
{
throw
new
Error
(
'TABLE_NAME environment variable is required'
)
;
}
Best Practices
Memory and Timeout Configuration
Memory
Start with 512MB for NestJS, 256MB for raw TypeScript
Timeout
Set based on cold start + expected processing time
NestJS: 10-30 seconds for cold start buffer
Raw TypeScript: 3-10 seconds typically sufficient
Dependencies
Keep
package.json
minimal:
{
"dependencies"
:
{
"aws-lambda"
:
"^3.1.0"
,
"@aws-sdk/client-dynamodb"
:
"^3.450.0"
}
,
"devDependencies"
:
{
"typescript"
:
"^5.3.0"
,
"esbuild"
:
"^0.19.0"
}
}
Error Handling
Return proper HTTP codes with structured errors:
export
const
handler
=
async
(
event
:
APIGatewayProxyEvent
)
:
Promise
<
APIGatewayProxyResult
>
=>
{
try
{
const
result
=
await
processEvent
(
event
)
;
return
{
statusCode
:
200
,
headers
:
{
'Content-Type'
:
'application/json'
}
,
body
:
JSON
.
stringify
(
result
)
}
;
}
catch
(
error
)
{
console
.
error
(
'Error processing request:'
,
error
)
;
return
{
statusCode
:
500
,
headers
:
{
'Content-Type'
:
'application/json'
}
,
body
:
JSON
.
stringify
(
{
error
:
'Internal server error'
}
)
}
;
}
}
;
Logging
Use structured logging for CloudWatch Insights:
const
log
=
(
level
:
string
,
message
:
string
,
meta
?
:
object
)
=>
{
console
.
log
(
JSON
.
stringify
(
{
level
,
message
,
timestamp
:
new
Date
(
)
.
toISOString
(
)
,
...
meta
}
)
)
;
}
;
log
(
'info'
,
'Request processed'
,
{
requestId
:
context
.
awsRequestId
}
)
;
Deployment Options
Quick Start
Serverless Framework:
service
:
my
-
typescript
-
api
provider
:
name
:
aws
runtime
:
nodejs20.x
functions
:
api
:
handler
:
dist/handler.handler
events
:
-
http
:
path
:
/
{
proxy+
}
method
:
ANY
AWS SAM:
AWSTemplateFormatVersion
:
'2010-09-09'
Transform
:
AWS
:
:
Serverless
-
2016-10-31
Resources
:
ApiFunction
:
Type
:
AWS
:
:
Serverless
:
:
Function
Properties
:
CodeUri
:
dist/
Handler
:
handler.handler
Runtime
:
nodejs20.x
Events
:
ApiEvent
:
Type
:
Api
Properties
:
Path
:
/
{
proxy+
}
Method
:
ANY
For complete deployment configurations including CI/CD, see
Serverless Deployment
.
Constraints and Warnings
Lambda Limits
Deployment package
250MB unzipped maximum (50MB zipped)
Memory
128MB to 10GB
Timeout
15 minutes maximum
Concurrent executions
1000 default (adjustable)
Environment variables
4KB total size
TypeScript-Specific Considerations
Bundle size
TypeScript compiles to JavaScript; use bundlers to minimize size
Cold start
Node.js 20.x offers best performance
Dependencies
Use Lambda Layers for shared dependencies
Native modules
Must be compiled for Amazon Linux 2
Common Pitfalls
Importing heavy libraries at module level
- Defer to lazy loading if not always needed
Not bundling dependencies
- Include all production dependencies in the package
Missing type definitions
- Install
@types/aws-lambda
for proper event typing
No timeout handling
- Use
context.getRemainingTimeInMillis()
for long operations
Security Considerations
Never hardcode credentials; use IAM roles and environment variables
Input Validation for Event Data
All incoming event data (API Gateway request bodies, S3 event objects, SQS message bodies) is untrusted external content; always validate and sanitize before processing to prevent injection attacks
Content Sanitization
When processing S3 objects or SQS message payloads, treat the content as untrusted third-party data; apply appropriate validation, schema checks, and sanitization before acting on it
Validate all input data
Use least privilege IAM policies
Enable CloudTrail for audit logging
Sanitize logs to avoid leaking sensitive data
References
For detailed guidance on specific topics:
NestJS Lambda
- Complete NestJS setup, dependency injection, Express/Fastify adapters
Raw TypeScript Lambda
- Minimal handler patterns, bundling, tree shaking
Serverless Config
- Serverless Framework and SAM configuration
Serverless Deployment
- CI/CD pipelines, environment management
Testing
- Jest, integration testing, SAM Local
Examples
Example 1: Create a NestJS REST API
Input:
Create a TypeScript Lambda REST API using NestJS for a todo application
Process:
Initialize NestJS project with
nest new
Install Lambda dependencies:
@codegenie/serverless-express
,
aws-lambda
Create
lambda.ts
entry point with Express adapter
Configure
serverless.yml
with API Gateway events
Deploy with Serverless Framework
Output:
Complete NestJS project structure
REST API with CRUD endpoints
DynamoDB integration
Deployment configuration
Example 2: Create a Raw TypeScript Lambda
Input:
Create a minimal TypeScript Lambda function with optimal cold start
Process:
Set up TypeScript project with esbuild
Create handler with proper AWS types
Configure minimal dependencies
Set up SAM or Serverless deployment
Optimize bundle size with tree shaking
Output:
Minimal TypeScript Lambda project
Optimized bundle < 50KB
Cold start < 100ms
Example 3: Deploy with GitHub Actions
Input:
Configure CI/CD for TypeScript Lambda with SAM
Process:
Create GitHub Actions workflow
Set up Node.js environment
Run tests with Jest
Bundle with esbuild
Deploy with SAM
Output:
Complete
.github/workflows/deploy.yml
Multi-stage pipeline
Integrated test automation
Version
Version: 1.0.0