AWS Lambda TypeScript Integration

Patterns for creating high-performance AWS Lambda functions in TypeScript with optimized cold starts.

Overview

Two approaches for TypeScript Lambda:

1. NestJS Framework - Dependency injection, modular architecture, larger bundle (100KB+)
2. 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

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:

1. Lazy Loading - Defer heavy imports until needed
2. Tree Shaking - Remove unused code from bundle
3. Minification - Use esbuild or terser for smaller bundles
4. 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<