This package implements the AWS Lambda Runtime Interface Client (RIC) for Node.js. It allows you to run Lambda functions in custom container images or local testing environments.
The RIC enables communication between your Lambda function code and the Lambda Runtime API, handling the invoke lifecycle including initialization, invocation, and error reporting.
- Node.js 22.x and above
npm install aws-lambda-ric
Create a handler file (e.g., index.js):
exports.handler = async (event, context) => { console.log('Event:', JSON.stringify(event, null, 2)); return { statusCode: 200, body: JSON.stringify({ message: 'Hello from Lambda!' }) }; };
When building custom Lambda container images, use the RIC as the entrypoint:
FROM public.ecr.aws/lambda/nodejs:22 # Copy function code COPY index.js ${LAMBDA_TASK_ROOT} # Install dependencies COPY package*.json ${LAMBDA_TASK_ROOT}/ RUN npm install CMD ["index.handler"]
For local testing, you can use the RIC with the AWS Lambda Runtime Interface Emulator:
# Build your container docker build -t my-lambda-function . # Run with RIE docker run -p 9000:8080 my-lambda-function # Invoke the function curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"message":"test"}'
You can build and run Lambda functions with the RIC on your own platform. Here's a minimal Dockerfile example:
FROM quay.io/centos/centos:stream9 AS build-image ARG NODE_VERSION=22.14.0 ARG FUNCTION_DIR="/function" # Install build dependencies RUN dnf -y install \ autoconf \ automake \ cmake \ gcc \ gcc-c++ \ libtool \ make \ python3 \ xz \ && dnf clean all # Install Node.js RUN ARCH=$(uname -m) && \ if [ "$ARCH" = "x86_64" ]; then NODE_ARCH="x64"; else NODE_ARCH="arm64"; fi && \ curl -fsSL https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz | \ tar -xJ -C /usr/local --strip-components=1 # Create function directory RUN mkdir -p ${FUNCTION_DIR} WORKDIR ${FUNCTION_DIR} RUN npm install aws-lambda-ric ENTRYPOINT ["npx", "aws-lambda-ric"] CMD ["index.handler"]
Build and run locally with RIE:
docker build -t my-lambda . docker run -p 9000:8080 \ -e AWS_LAMBDA_FUNCTION_NAME=test \ -v ~/.aws-lambda-rie:/aws-lambda \ --entrypoint /aws-lambda/aws-lambda-rie \ my-lambda npx aws-lambda-ric index.handler
- Node.js 22.x or later
- npm
- Docker (for container builds)
# Clone the repository git clone https://github.com/aws/aws-lambda-nodejs-runtime-interface-client.git cd aws-lambda-nodejs-runtime-interface-client # Install dependencies npm install # Run all tests with coverage and linting npm test # Run unit tests only npm run test:unit # Run integration tests only npm run test:integ # Run linter npm run lint # Fix linting issues npm run lint:fix # Clean build artifacts npm run clean
Build TypeScript and package for distribution:
npm run build
This runs tests, compiles TypeScript, and packages the output.
Individual steps:
npm run compile # TypeScript compilation only npm run pkg # Package with esbuild
Complete build including native module compilation for Linux:
npm run build:container
- Builds using Docker on AL2023 base image
- Compiles native C++ dependencies (curl, aws-lambda-cpp)
- Produces deployable artifacts in
build-artifacts/ - Targets
linux/amd64by default for Lambda compatibility - Use
PLATFORM=linux/arm64 npm run build:containerfor ARM64 Lambda
To test the runtime using the AWS Lambda Runtime Interface Emulator:
# Build the project (one-time) npm run build:container # Run with RIE npm run peek:rie # In another terminal, invoke the function curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"message":"test"}'
For multi-concurrent testing:
npm run peek:rie:mc
To explore the built package in an interactive container:
npm run peek:container
To deploy and test as a Lambda container function:
# Build the project npm run build:container # Review and update variables in scripts/lambda-build.sh # Build and deploy (requires AWS credentials) npm run peek:lambda
The RIC consists of several components:
- Runtime Client: Communicates with the Lambda Runtime API
- Context Builder: Constructs the Lambda context object
- Function Loader: Loads and resolves user handler functions
- Logging: Handles structured logging to CloudWatch
- Streaming: Supports response streaming for applicable invocation modes
The RIC includes a native C++ module for high-performance communication with the Lambda Runtime API. This module is built using:
- aws-lambda-cpp - AWS Lambda C++ runtime
- curl - HTTP client library
Pre-built archives for these dependencies are included in the deps/ directory.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
See CONTRIBUTING.md for information on reporting security issues.