lambda-local-runner

Run one or more AWS Lambda handlers locally via Express. Perfect for local development, testing, and integration.

Installation

npm install lambda-local-runner
# or globally
npm install -g lambda-local-runner
Copy

Quick Start

Single Lambda

import { runLambdaLocally } from 'lambda-local-runner';
import { handler } from './myLambda';

runLambdaLocally(handler, { port: 3000, enableCors: true });
Copy

Multiple Lambdas

import { runMultipleLambdas } from 'lambda-local-runner';

runMultipleLambdas({
  port: 4000,
  routes: [
    { path: '/users', handler: userHandler },
    { path: '/orders', handler: orderHandler }
  ]
});
Copy

CLI Usage

# Single Lambda (direct CLI)
lambda-local-runner --single=./myLambda.ts --port=3000

# Multiple Lambdas (direct CLI)
lambda-local-runner --routes=/users:./users.ts,/orders:./orders.ts --port=4000
Copy

Run via npm script (in this repo only)

You can also run the CLI using the npm script provided in this repository:

# Single Lambda
npm start -- --single=./myLambda.ts --port=3000

# Multiple Lambdas
npm start -- --routes=/users:./users.ts,/orders:./orders.ts --port=4000
Copy

Note: The above npm scripts only work in this repository. If you install lambda-local-runner in another project, see the next section.

Usage from another project

If you install lambda-local-runner as a dependency in another project, you can:

• Use npx lambda-local-runner ... to run the CLI
• Or add your own npm script in your project's package.json that calls lambda-local-runner

---

📦 Using in Another Project

After installing lambda-local-runner as a dependency in your project:

1. Run with npx

npx lambda-local-runner --single=./myLambda.ts --port=3000
Copy

2. Add an npm script

Add this to your project's package.json:

"scripts": {
  "lambda-local": "lambda-local-runner --single=./myLambda.ts --port=3000"
}
Copy

Then run:

npm run lambda-local
Copy

Tip:

• You can adjust the arguments as needed for your use case (e.g., use --routes for multiple handlers).
• The CLI will be available as lambda-local-runner in your project's node_modules/.bin, so you can use it in any custom script or toolchain.
• For TypeScript handlers, ensure you have a build step or use ts-node/register if needed.

AWS Credentials Requirement

⚠️ Important: If your Lambda code interacts with AWS services (S3, DynamoDB, etc.), you must provide AWS credentials locally.

Environment Variables

export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
export AWS_REGION=us-east-1
Copy

Credentials File

Create ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
region = us-east-1
Copy

📚 Documentation & Storybook

• TypeDoc API Docs:

  • Generate API documentation with npm run typedoc (output in the docs/ folder).
  • You can publish these docs to GitHub Pages for easy sharing.

• GitHub Pages:

  • Host your generated TypeDoc documentation or Storybook on GitHub Pages for public access.
  • See GitHub Pages documentation for setup instructions.

• Storybook (optional):

  • If you have UI components or want to demo Lambda handler responses visually, you can add Storybook to your project.
  • Run npx storybook init to set up, then add stories for your handlers or Express endpoints as needed.
  • Storybook can also be published to GitHub Pages.

---

Features

✅ Single or multiple Lambda handlers
✅ Automatic CORS support
✅ CLI tool included
✅ Works with AWS services (with credentials)
✅ TypeScript support
✅ Full TypeDoc documentation

License

MIT