Introduction

When developing AWS Lambda functions with Node.js, it’s important to be able to debug and test your code locally before deploying it to the cloud. AWS SAM (Serverless Application Model) provides tools and frameworks that make local Lambda debugging easier. In this guide, we’ll walk through setting up AWS Lambda for local debugging using Node.js and the AWS SAM CLI.

Prerequisites

• Node.js installed on your machine (You can download it from nodejs.org)
• AWS CLI configured with your AWS credentials (AWS CLI Setup)
• AWS SAM CLI installed on your machine (AWS SAM CLI Setup)
• An AWS account with Lambda permissions

Step 1: Create a Basic Lambda Function

First, let’s create a basic AWS Lambda function to be used in this local debugging setup. Here is a simple Node.js Lambda function:

const aws = require('aws-sdk');

exports.handler = async (event) => {
    console.log("Event:", JSON.stringify(event, null, 2));
    return {
        statusCode: 200,
        body: JSON.stringify({ message: 'Hello from Lambda!' }),
    };
};
            

Save this as index.js in a new directory on your local machine. This is a simple Lambda function that logs the event and returns a message.

Step 2: Initialize a SAM Application

AWS SAM CLI allows you to run AWS Lambda functions locally in a Docker container that simulates the Lambda execution environment. Let’s set up a basic SAM application to test our Lambda locally.

1. Open your terminal and navigate to the directory where you saved your index.js file.
2. Run the following command to initialize a new AWS SAM project:

sam init

Follow the prompts to create a basic Lambda function with Node.js as the runtime. Select the “Hello World” example when asked for a template. This will create the necessary files for your AWS Lambda project.

Step 3: Modify Your Template

In the SAM project folder, you’ll see a template.yaml file. Open this file and modify it to reference your custom Lambda function (the index.js you created earlier).

Resources:
  MyLambdaFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs14.x
      CodeUri: .
      MemorySize: 128
      Timeout: 3
            

This will ensure that your Lambda function uses the index.handler (your index.js file) as the handler for execution.

Step 4: Run Lambda Locally

Now that your Lambda function and template are set up, let’s run it locally using the AWS SAM CLI. AWS SAM allows you to invoke Lambda functions locally in a Docker container that mimics the Lambda environment.

1. Make sure Docker is installed and running on your machine. You can download it from Docker’s official site.
2. In your terminal, navigate to the SAM project folder and run the following command to start your Lambda function locally:

sam local invoke

This command will simulate invoking your Lambda function locally. You should see output similar to the following:

Invoking index.handler (nodejs14.x)
{
  "statusCode": 200,
  "body": "{\"message\":\"Hello from Lambda!\"}"
}
            

If you see the expected output, that means the Lambda function is running correctly in the local environment.

Step 5: Debugging Locally with Node.js

To debug your Lambda function locally, you can use Node.js’s built-in debugger. First, modify your Lambda function to include a debugger; statement where you want to start debugging:

exports.handler = async (event) => {
    debugger; // Debugging here
    console.log("Event:", JSON.stringify(event, null, 2));
    return {
        statusCode: 200,
        body: JSON.stringify({ message: 'Hello from Lambda!' }),
    };
};
            

Then, run the following command in your terminal to invoke the Lambda function locally in debug mode:

sam local invoke -d 5858

The -d 5858 flag tells AWS SAM CLI to run the Lambda function in debug mode and listen for incoming connections on port 5858. Open your IDE (like VS Code) and attach the debugger to port 5858. You can now step through your code and debug it as it runs locally.

Step 6: Testing with Event Data

If your Lambda function expects event data (such as data from an API Gateway or S3), you can pass this data in as a JSON file when invoking the function locally. For example, create an event.json file with the following contents:

{
  "key": "value"
}
            

Then, invoke your Lambda function with the event file:

sam local invoke -e event.json

This will pass the contents of event.json as the event parameter to your Lambda function.

Conclusion

With AWS SAM CLI and Docker, you can easily set up local debugging for your AWS Lambda functions written in Node.js, providing an efficient and streamlined development process. By invoking and testing your functions locally, you can catch bugs early, fine-tune your code, and ensure that your Lambda functions work as expected before deploying them to the cloud.

Happy coding with AWS Lambda and Node.js!