node-lambda for Local Runs and Amazon Lambda Deployment

Why node-lambda Exists for Node.js Lambda Developers

node-lambda addresses the gap between editing a Node.js Lambda function and running that same handler in its intended event context. A developer can provide JSON for an event and additional context, invoke the selected handler locally, create a deployment archive, and send the result to Amazon Lambda without first converting the project into a larger framework. That makes the tool relevant to small Node.js functions, service scripts, and teams that prefer direct AWS deployment over a separate application structure.

The project organizes the workflow around four commands: `setup`, `run`, `package`, and `deploy`. This is more specific than a generic file transfer utility. Local invocation uses the configured handler and JSON inputs, while packaging handles dependencies and exclusions before deployment. The README also points to separate JavaScript and TypeScript example applications, but those examples are not required components of node-lambda itself.

node-lambda is not a complete AWS infrastructure manager. Its documented deployment variables cover a function's runtime, handler, role, memory, timeout, architecture, networking, tracing, layers, tags, dead-letter queue, and related settings. That is a substantial set of function deployment options, but the README does not describe provisioning IAM policies, API Gateway routes, databases, or other cloud resources as part of this CLI.

How node-lambda Connects Events, Handlers, Archives, and AWS

The documented local flow begins with `event.json`. The `run` command reads that file and passes its data to the Lambda event object. A separate `context.json` can add mock context data, which gives developers separate control over the two inputs. The selected entry point is controlled by `AWS_HANDLER`, with `index.handler` as the displayed default for `run`. A timeout for local execution is controlled separately through `AWS_RUN_TIMEOUT`.

The packaging stage prepares the project for Amazon Lambda. It can install dependencies with `npm` or `yarn`, retain the current `node_modules` directory, mount additional Docker volumes when a Docker image is supplied, consume a prebuilt directory, and apply exclusion globs. Those controls matter because the deployment archive must represent the intended function code. The README does not specify one generated archive name for every case, so developers should inspect the output produced by `package` rather than assume a filename.

Deployment configuration is loaded from `.env`. The documented `deploy.env` has the same format and is intended for environment variables that need to accompany the code but should not be committed. Configuration can also come from a named AWS environment, profile, endpoint, region list, or configuration file. The package includes the AWS SDK and the CLI exposes AWS-related controls, but the repository overview does not establish the exact internal sequence of AWS calls.

Event sources are represented through `event_sources.json`, and the README explicitly warns that not every event source available in Lambda is supported. This boundary makes node-lambda a focused invocation and deployment tool, not a complete simulator for every AWS event type.

Installing node-lambda and Preparing Its Files

The shortest documented installation uses `npx`, so a separate global installation is not required. The `@latest` tag asks npm for the latest published version whenever the command is invoked. A global installation is available when a persistent `node-lambda` executable is preferred.

$ npx node-lambda@latest setup

The `setup` command initializes `event.json`, `context.json`, `.env`, `deploy.env`, and `event_sources.json`. Run `setup --help` when the defaults shown in the README are not sufficient. It exposes event and context file options, while most deployment settings are entered through `.env`.

The project recommends excluding generated and sensitive files from version control. This command appends the four documented entries to `.gitignore`.

$ echo -e ".env\ndeploy.env\nevent.json\n.lambda" >> .gitignore

After setup, the project should contain the generated configuration and input files. `deploy.env` is particularly important for deployment-only configuration, while `.env` is described as the deployment configuration file. The README does not document a built-in secret scanner, so excluding these files is a repository hygiene requirement rather than a substitute for reviewing their contents.

Running a Handler with event.json and context.json

The first local use is `run`. By default, the displayed command targets `index.handler`, reads `event.json`, uses `context.json`, and applies the runtime and timeout settings from configuration. The event file can represent a Lambda-style request, while the context file lets a developer vary context data independently.

$ npx node-lambda@latest run

Command help lists controls for changing the handler, event file, runtime, timeout, configuration file, context file, proxy, and API Gateway conversion. Multiple events are enabled by default through `--enableRunMultipleEvents`. The `--proxy` option can start a proxy server, while `--apiGateway` converts the input for API Gateway processing. The README does not provide a ready-to-use example event payload, so an existing project should supply the shape its handler expects.

This is useful for deterministic handler checks, but it is not documented as identical to Amazon Lambda. The README describes event and context injection, not complete reproduction of the AWS execution environment. Network behavior, concurrency, service integrations, and permissions can therefore remain different from deployed execution. For a server behind HTTP, the proxy option is the documented mechanism for receiving requests locally rather than repeatedly editing the event file by hand.

Packaging and Deploying Through the node-lambda CLI

`package` creates the local archive used for deployment. Before packaging, the project must already expose a Lambda handler and have a `package.json` from which node-lambda can derive defaults when needed. The documented default function name can come from `package.json.name` or fall back to `UnnamedFunction`, while the handler defaults to `index.handler`.

$ npx node-lambda@latest package

The packaging options show several deployment choices. `--packageManager` accepts `npm` or `yarn`; `PACKAGE_DIRECTORY` can select a local package directory; `EXCLUDE_GLOBS` can omit files such as local events or samples; and `PREBUILT_DIRECTORY` accepts code that has already been prepared. A Docker image can also be provided for dependency installation through `--dockerImage`.

Deployment is exposed as the fourth top-level command.

$ npx node-lambda@latest deploy

The documented configuration includes AWS credentials through `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, temporary credential settings through `AWS_SESSION_TOKEN`, and named access through `AWS_PROFILE`. It also documents endpoint and environment selection, function versioning, VPC subnets and security groups, tracing, layers, log retention, dead-letter target, tags, S3-assisted deployment, zip file deployment, and container image deployment through `IMAGE_URI`.

This creates several paths through one CLI, but the README excerpt does not provide the complete `deploy --help` output. It would be unsafe to infer precedence among `.env`, command-line options, profiles, or multiple artifact types. Developers should review the command help for the installed release before combining those settings.

Runtime Compatibility, Maintenance, and Upgrade Cost

The repository's last push was on 2026-08-11, so it is not archived and has a recent recorded change. Its published release history is older: version `0.22.0` was released on 2022-02-17, followed by `0.21.0` on 2021-11-10 and `0.20.0` on 2021-09-25. The repository `package.json` reports version `1.3.0` and requires Node.js `>= 18.0.0`. This difference between package metadata, release history, and README defaults means version checks matter before deployment.

The clearest compatibility warning is the documented `AWS_RUNTIME` default of `nodejs16.x`. Developers must choose a currently supported runtime that matches their function and verify it against their AWS account before packaging. The README does not prescribe a replacement runtime value, so this review does not invent one.

Upgrades can affect more than the CLI package. A newer node-lambda may change command options, dependency installation behavior, archive contents, or AWS SDK handling. The project requires Node.js 18 or later, so adopting a newer tool version may also raise the local runtime floor. The dependency list includes the AWS SDK v2 line, `commander`, `archiver`, `proxy-agent`, tracing support, and configuration handling, which means dependency changes should be reviewed when moving across releases.

The repository declares the `BSD-2-Clause` license. The `LICENSE` file is the source for its exact terms. That declaration permits reuse under the license's conditions, but organizations with compliance requirements still need to inspect the license text and dependency licenses. The project license does not by itself settle obligations imposed by separately distributed dependencies.

Where node-lambda Falls Short and What to Use Instead

The first limitation is simulation scope. `run` injects an event and context, but the README does not claim that the command reproduces the full Amazon Lambda environment. It also states that `event_sources.json` cannot represent every Lambda event source. A handler that depends on precise AWS event semantics or service integrations needs deployment-level verification.

The second limitation is configuration age. The displayed default runtime is `nodejs16.x`, even though the current `package.json` requires Node.js 18 or later and the repository was pushed more recently. A developer who accepts defaults without reviewing them can package for the wrong runtime.

The third limitation is infrastructure coverage. node-lambda configures and deploys the Lambda function, but the README does not present API creation, IAM role creation, databases, or infrastructure-as-code workflows as managed operations. A developer who needs a complete serverless stack may prefer a cloud-specific framework that provisions resources from a template and derives deployment settings from that template. The actual difference is scope: node-lambda centers on a handler-oriented CLI and local files, while a provisioning framework owns resource definitions and their dependencies.

A pipeline-based deployment process is another alternative when repeatability and review gates matter more than local convenience. That approach packages code through CI and hands deployment to configured stages, whereas node-lambda exposes packaging and deployment directly to the developer. Neither path is inherently superior; their trade-off is operational control versus a project-local interface.

Editorial conclusion

Adopt node-lambda if you want a small, file-driven CLI for local Lambda invocation and deployment from the same project. Do not adopt it if your organization requires container image deployment as its only workflow, comprehensive event-source simulation, or infrastructure provisioned as code. Before the first deployment, verify AWS credentials and permissions, replace the documented nodejs16.x runtime default, confirm the packaged handler path, and inspect `package.json` and generated configuration for the current Node.js environment.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. motdotla/node-lambda on GitHub
4. README
5. Releases