AWS Lambda TypeScript Integration
Patterns for creating high-performance AWS Lambda functions in TypeScript with optimized cold starts.
Overview
Two approaches for TypeScript Lambda:
- NestJS Framework - Dependency injection, modular architecture, larger bundle (100KB+)
- Raw TypeScript - Minimal overhead, smaller bundle (<50KB), maximum control
Both support API Gateway and ALB integration.
When to Use
- Creating new Lambda functions in TypeScript
- Optimizing cold start performance
- Choosing between NestJS and minimal TypeScript
- Configuring API Gateway or ALB integration
- Setting up CI/CD 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:
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:
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:
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
const dynamoClient = new DynamoDBClient({ region: process.env.AWS_REGION });
export const handler = async (event: APIGatewayProxyEvent) => {
};
Environment Configuration
export const env = {
region: process.env.AWS_REGION || 'us-east-1',
tableName: process.env.TABLE_NAME || '',
debug: process.env.DEBUG === 'true',
};
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<
