AWS Lambda Typescript Integration Agent Skill

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:

// 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

Deployment Validation

Pre-deploy checks:

• Run npm test - verify all tests pass
• Run npm run build - confirm TypeScript compiles without errors
• Verify bundle size < 50MB (unzipped)
• Run serverless invoke local or sam local invoke - test locally

Post-deploy verification:

• Run serverless invoke or aws lambda invoke - verify handler executes
• Test API endpoint via curl or Postman
• Check CloudWatch logs for errors
• Verify cold start time meets SLA

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

Validation:

• Run serverless invoke local -f api - verify handler works
• Check bundle size < 250MB
• Test deployed endpoint returns 200 OK

Output: NestJS project with REST API, DynamoDB integration, deployment config

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

Validation:

• Run sam local invoke - test locally before deploying
• Verify bundle < 50KB with du -sh dist/
• Confirm cold start < 100ms via CloudWatch

Output: Minimal TypeScript Lambda, 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

Validation:

• Verify CI pipeline runs npm test successfully
• Confirm sam validate passes in pipeline
• Check CloudFormation stack created successfully

Output: GitHub Actions workflow, multi-stage pipeline, test automation

Version

Version: 1.0.0