Create, Test, and Deploy a Typescript Lambda with CDK

I’ve always wondered why there isn’t a create-react-app type template for creating Lambdas, and while we aren’t going to create that now, we’ll go over the basic steps for creating a Typescript-based Lambda, testing it locally, and deploying it to an AWS environment.

If you’re used to manually deploying your Lambdas, CDK may be new to you. Not only are we going to build the container that will store our Lambda handler code, but CDK will also define the infrastructure and help us deploy it all to our AWS account. This will likely be a bit overwhelming (and there’s a lot of boilerplate), but once you get the hang of it things will be much easier than doing things manually.

Prerequisites

We’ll be using the AWS CLI tools for CDK and SAM. CDK will create a CloudFormation Stack for us which will contain the definition of all the infrastructure we need (eg. a Lambda and an API Gateway). We’ll also use SAM, but only to allow for local testing of our Lambda code.

There are a few things you’ll need to do before we can get started.

• Create an AWS account
• Install the AWS CLI
• Setup your AWS credentials with aws configure
• Install CDK CLI (or npm install -g aws-cdk)
• Install SAM CLI
• Install Docker

Scaffolding

Create the basic template for your infrastructure using CDK.

$ mkdir my-lambda
$ cd my-lambda
$ cdk init --language typescript

This creates a blank CloudFormation Stack. Open the Stack definition file found at ./lib/my-lambda-stack.ts. You should find a class called MyLambdaStack with an empty constructor.

Inside this constructor is where we will tell CDK what other resources we need. In our case we will add a Lambda and an API Gateway, but we’ll get to that later.

If you’re curious at this point, you can run the following command to see what resources are in the Stack.

$ cdk synth

This should spit out YAML code to the terminal that defines everything in our stack. Although it will return a lot of text, it basically doesn’t contain much for infrastructure at this point.

We’ll run this code again later to create a SAM Template, which will be used to synthesize a virtual environment that we can run locally to test our Lambda code.

Create Your Lambda Handler

If you’re already familiar with Lambdas, this is the easy part. We’re just going to create a Typescript file that exports a Lambda handler.

We’ll install an NPM package called aws-lambda that has a few classes we need and then we’ll create a new folder to store your Lambda code.

$ npm install aws-lambda
$ npm install --save-dev @types/aws-lambda
$ mkdir src
$ cd src
$ touch lambda.ts

Inside lambda.ts we’ll create a basic Lambda handler.

import { APIGatewayProxyHandler } from "aws-lambda";

export const handler: APIGatewayProxyHandler = async (event) => {
 const body = {
   message: "Hello from Lambda!",
 };
 return {
   statusCode: 200,
   body: JSON.stringify(body),
 };
};

Transpiling Typescript

Although all the code that was autogenerated for us is in Typescript, there is actually no mechanism currently in place to transpile our Lambda function into Javascript (the Lambda runtime cannot currently interpret Typescript) so we’ll need to do that ourselves.

A basic tsconfig.json file was created when we ran cdk init, but it's missing a few things. We’ll need to add an outDir and an include property so the Typescript transpiler (tsc) will know what to transpile and where to put it.

After adding these properties, your tsconfig.json should look something like this.

{
 "compilerOptions": {
   "target": "ES2020",
   "module": "commonjs",
   "lib": [
     "es2020",
     "dom"
   ],
   "declaration": true,
   "strict": true,
   "noImplicitAny": true,
   "strictNullChecks": true,
   "noImplicitThis": true,
   "alwaysStrict": true,
   "noUnusedLocals": false,
   "noUnusedParameters": false,
   "noImplicitReturns": true,
   "noFallthroughCasesInSwitch": false,
   "inlineSourceMap": true,
   "inlineSources": true,
   "experimentalDecorators": true,
   "strictPropertyInitialization": false,
   "typeRoots": [
     "./node_modules/@types"
   ],
   "outDir": "dist",
 },
 "include": [
   "src/**/*",
 ],
 "exclude": [
   "node_modules",
   "cdk.out"
 ]
}

Now run the build command to make sure it worked.

$ npm run build

This should have created a ./dist folder that now contains the transpiled version of your Lambda function.

Updating the CDK Stack

Now that we have our Lambda handler and it’s transpiling to Javascript, we can tell our CDK Stack that it exists.

Go back to the Stack definition file (./lib/my-lambda-stack.ts) and replace it with the following.

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigateway from "aws-cdk-lib/aws-apigateway";

export class MyLambdaStack extends cdk.Stack {
 constructor(scope: Construct, id: string, props?: cdk.StackProps) {
   super(scope, id, props);

   // The code that defines your stack goes here
   const handler = new lambda.Function(this, "MyLambdaHandler", {
     runtime: lambda.Runtime.NODEJS_20_X,
     code: lambda.Code.fromAsset("./dist"),
     handler: "lambda.handler",
   });
   const api = new apigateway.RestApi(this, "MyLambdaHandlerApi", {
     restApiName: "My Lambda",
     description: "This is my API for my Lambda",
   });
   const getLambdaIntegration = new apigateway.LambdaIntegration(handler);
   api.root
     .addResource("run-my-function")
     .addMethod("GET", getLambdaIntegration);
 }
}

Note: notice that we’ve added an API Gateway that responds to the resource /run-my-function. We’ll need this later when we try to invoke our Lambda.

Running Locally with SAM

Now we can test our Stack and Lambda handler locally.

To do so, we need to autogenerate a template.yml from the synthesized CloudFormation Stack so that SAM can read it. We can simply take the output from cdk synth and route it to a file.

$ cdk synth --no-staging > template.yml

Note: Every time we make a change to the Stack we’ll need to update the template.yml for SAM. You may want to add a script to your package.json to do this.

Because our Stack only contains a single Lambda we can run the following command with no parameters. If you add multiple Lambdas you’ll need to pass in the ID of the Lambda function you want to run.

$ sam local invoke

Running this should return something similar to the following.

$ sam local invoke
Invoking lambda.handler (nodejs20.x)                                                                                                                  
Local image is up-to-date                                                                                                                             
Using local image: public.ecr.aws/lambda/nodejs:20-rapid-x86_64.                                                                                      
                                                                                                                                                      
Mounting /my-lambda/dist as /var/task:ro,delegated, inside runtime container                                      
START RequestId: 786c4a20-2873-4de4-b06a-cdd63fe650cd Version: $LATEST
END RequestId: 4ac6a0bd-df07-419f-9c02-5ce37fc38a2d
REPORT RequestId: 4ac6a0bd-df07-419f-9c02-5ce37fc38a2d	Init Duration: 0.41 ms	Duration: 781.81 ms	Billed Duration: 782 ms	Memory Size: 128 MB	Max Memory Used: 128 MB	
{"statusCode": 200, "body": "{\"message\":\"Hello from Lambda!\"}"}

And there you have it! You ran your Lambda locally.

Deploying to AWS

CDK requires a “bootstrapping” step which installs a CDK CloudFormation Stack in your AWS environment which contains the tools that will be used later when you deploy your new Lambda.

Run the following command and follow the instructions.

$ cdk bootstrap

Now you’re ready to deploy your Lambda to your AWS environment. All you need to do is tell CDK to do it.

$ cdk deploy

This will analyze your Stack and deploy the changes to your Stack to your AWS environment. When this completes, you should see the following towards the bottom of your terminal.

Outputs:
MyLambdaStack.MyLambdaHandlerApiEndpoint72F57D33 = https://8h6xas3xoy2.execute-api.us-east-1.amazonaws.com/prod/

You can copy that URL, append the API Gateway resource from earlier to it, and run it in a browser or using curl.

$ curl https://8h6xas3xoy2.execute-api.us-east-1.amazonaws.com/prod/run-my-function
{"message":"Hello from Lambda!"}

If you’re done with this test and want to delete everything we just created, just tell CDK to destory it.

$ cdk destroy

Get Shit Done

Our team has built hundreds of Lambdas over the years and it’s always baffled me how poor the documentation is for setting up something so simple.

What can we help you build?