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](#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