@capybaracode/awslocal v1.4.1

awslocal

awslocal lets you test NodeJS Amazon Lambda functions on your local machine, by providing a simplistic API and command-line tool.

It does not aim to be perfectly feature proof as projects like serverless-offline or docker-lambda, but rather to remain very light (it still provides a fully built Context, handles all of its parameters and functions, and everything is customizable easily).

The main target are unit tests and running lambda functions locally.

ATTENTION: awslocal was based on lambda-local.

Prerequisites

• Node.js >= 18
• Typescript >= 5
• ts-node >= 10.9.1

Install

Global installation

npm install -g awslocal 

Project installation

npm install awslocal --save-dev

About: CLI

Arguments

• init - Create awslocal settings file. more details

• -i, --init Create awslocal settings file. more details

• -c, --config Path to the config file. Default: /.awslocal.json
• -l, --lambda-path <path> Path to the lambda handler
• -h, --lambda-handler <handler> Handler name
• -t, --timeout <number> Timeout in seconds
• -p, --profile <profile> AWS profile
• -r, --region <region> AWS region
• -e, --env-path <path> Path to the .env file
• -E, --event-path <path> Path to the event file
• -P, --port <number> Port
• -V, --version Output the version number.
• -H, --help Show help.

Settings

By default awslocal looks for the .awslocal.json file in the root of the project. This file contains the basic settings to emulate a lambda, apigateway proxy integration, sns, sqs and other aws services that integrate with AWS Lambda.

.awslocal.json

{
    "lambda": {
        "path": "path/to/handler",
        "handler": "handler",
        "timeout": 3,
        "env": ".env"
    },
    "aws": {
        "region": "us-east-1",
        "profile": "default"
    },
    "port": 9000,
    "apigateway": {
        "restApiId": "your-rest-api-id",
        "resources": [
            {
                "resource": "your/path/{id}",
                "method": "GET",
                "hasAuthorizer": false
            }
        ],
        "authorizer": {
            "context": {
                "yourKey": "your-value"
            },
            "functionName": "your-authorizer-function-name"
        }
    }
}

tsconfig.json

Add the configuration below to your tsconfig.json

{
  ...
  "ts-node": {
    "esm": true
  }
}

Usage

It is possible to use awslocal via command line or via vscode debug, below are some examples of use.

Step 1

create the .awslocal.json configuration file. To make it easier, you can use the command below.

npx awslocal --init

After this command, the .awslocal.json file will be created in the root of the project, with the default settings.

Remember that it is necessary to define the lambdaPath path in the created file.

Step 2

In this step we will actually emulate AWS Lambda on our local machine. The two ways to do this, the first via the command line and the second via the vscode debug, both create a server that will wait to receive the inputs

Via command line

npx awslocal

Via vscode debug

To run via vscode, you need to create a .vscode/launch.json file and copy and paste the json below.

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debugs via awslocal",
      "skipFiles": ["<node_internals>/**"],
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/awslocal",
      "cwd": "${workspaceFolder}",
      "args": ["--config", ".awslocal.json"],
      "outputCapture": "std"
    }
  ]
}

After this configuration, just press F5 or the run debug button

Without .awslocal.json

you can emulate a lambda directly from the command line, passing the basic data. Path to the file that contains the lambda handler + path to the json file that will be the lambda input.

npx awslocal -l /path/to/lambda/file -E /path/to/test-event.json

Step 3

Now use Postman or any program that can make an http call, so you can pass the input you would pass to the lambda, see the example below

curl --location 'http://localhost:9000/lambda-invoke' \
--header 'Content-Type: application/json' \
--data '{}'

Examples

Lambda

curl --location 'http://localhost:9000/lambda-invoke' \
--header 'Content-Type: application/json' \
--data '{}'

Lambda + API Gateway proxy integration

curl --location --request PUT 'http://localhost:9000/apigateway-invoke/users/1234567489' \
--header 'Content-Type: application/json' \
--data '{
    "foo": "foo"
}'

Lambda + SNS integration

curl --location --request PUT 'http://localhost:9000/sns-invoke' \
--header 'Content-Type: application/json' \
--data '[
  {
    "subject": "Optional subject",
    "message": {
      "yourProperty": "Your data object"
    },
    "messageAttributes": {
      "yourProperty": {
        "DataType": "String",
        "StringValue": "Your data object"
      }
    }
  }
]'

Lambda + SQS integration

curl --location --request PUT 'http://localhost:9000/sqs-invoke' \
--header 'Content-Type: application/json' \
--data '[
  {
    "messageGroupId": "message-group-id",
    "messageDeduplicationId": "message-deduplication-id",
    "message": {
      "yourProperty": "Your data object"
    },
    "messageAttributes": {
      "yourProperty": {
        "dataType": "String",
        "stringValue": "Your data object",
        "stringListValues": [],
        "binaryListValues": []
      }
    }
  }
]'