/aws-lambda-typescript-integration

name: aws-lambda-typescript-integration
description: Provides AWS Lambda integration patterns for TypeScript with cold start optimization. Use when creating or deploying TypeScript Lambda functions, choosing between NestJS framework and raw TypeScript approaches, optimizing cold starts, configuring API Gateway or ALB integration, or implementing serverless TypeScript applications. Triggers include "create lambda typescript", "deploy typescript lambda", "nestjs lambda aws", "raw typescript lambda", "aws lambda typescript performance".
allowed-tools: Read, Write, Edit, Glob, Grep, Bash

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

| 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](#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](references/raw-typescript-lambda.md#cold-start-optimization) 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, m