Develop a Lambda Function Locally Using Visual Studio Code

5/20/2023

Get VS Code Configured

You need the AWS Toolkit for VS Code. Install it from within VS Code by opening Extensions, and then search for aws toolkit. For this example, we'll be making a Node.js function, so you need npm, and the Node.js SDK. You also need Docker.

The AWS docs recommend installing the AWS SAM CLI. While we're not developing a serverless application here, we need it. Go ahead and install it. If you already have it, make sure you're using the latest stable version.

The AWS docs also recommend connecting VS Code to an AWS account. You don't have to do this to run the Lambda function locally. Unless you want to for some other reason, you do not have to set up an AWS profile for this.

Create a New Serverless Application

Run AWS: Create Lambda SAM Application from the VS Code Command Palette. Choose nodejs16.x (don't pick the one that says nodejs16.x (Image)). Choose arm64 as the architecture. Why? While testing locally doesn't cost you anything, you might wind up deploying your Lambda at some point, and AWS charges less for Lambda invocations that use Arm. Choose AWS Sam Hello World as the application template.

Choose to select a folder for the application, and create one specifically for this purpose. Call the folder anything you want, like my-lambda.

Lastly, choose a name for the new SAM application. The name VS Code suggests is fine: lambda-nodejs16.x.

Now, if you look in the folder you created, you'll see a subfolder named using the name you provided for the new SAM application. Inside it, you will see a folder named hello-world and in that you'll see a file named app.js. That's a simple Lambda function.

Set Up Debugging for the Application

What good is developing if you can't debug? In the folder that was created for your new application, find and open the file named template.yaml. This file is used by AWS SAM to define resources for the application. In our case, there's only one resource: the Lambda function. Look just under the line that says Resources:. You'll see some text that says "AWS: Add Debug Configuration." Click on that. Your workspace file will open up. You can just close it without changing anything. VS Code just added a bunch of boilerplate to it, which is good enough for our purposes.

Debug Your Application

Go to Run and Debug. Make sure that your Lambda function's name shows up in the dropdown box. Click on the green Play button. In our case, you'll see in the output that a Docker image is fetched: public.ecr.aws/sam/emulation-nodejs16.x. That's where the Lambda function is locally executed.

Try placing a breakpoint in your Lambda function and hitting the green Play button again. This time, execution will stop at the breakpoint, and you can see the values of variables used by your Lambda function.

Current Oddity With Debugging

Even with no breakpoints set, when you debug your Lambda, the debugger will stop on a line that says "promiseInitHook" inside a function named "promiseInitHookWithDestroyTracking." This is documented in a GitHub issue. A future release of VS Code is supposed to resolve the issue.

Develop Your Application

From here, you can make changes as needed. Rewrite the Lambda function to do what you want it to. Lambda functions are driven by JSON data that is passed in to them in the form of an "event." You can the AWS SAM CLI to generate mock events for a variety of services. For example, run aws sam local generate-event s3 put and see the JSON that is returned. You can send anything you want to your local Lambda, like a sample event from the SAM CLI. Next to where you've been clicking on the green Play button, click on the gear icon instead. That opens up the launch.json file for your SAM application. Find "lambda" and, underneath it, "payload." For "payload", add "path" and set it to the path of the events.json in the events folder of your application. The contents of that file will be passed in to your Lambda function. For example:

"lambda": {
    "payload": {
        "path": "${workspaceFolder}/lambdas/lambda-nodejs16.x/events/event.json",
    },
    "environmentVariables": {},
    "runtime": "nodejs16.x"
}

When you're done testing and developing, deploy your Lambda to AWS.

Run Your Application Without VS Code

If you just want to run your Lambda and see what it outputs without using the debugger, you can also just do it from the command line. Navigate to the directory where your Lambda function resides, and run:

sam local invoke

If you want to use your event.json file, then run:

sam local invoke -e events/event.json