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

Explore the full documentation, architecture, and deep technical notes for this project on DeepWiki:

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

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

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

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

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

# 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

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

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

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

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

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

Add this to your project's package.json:

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

Then run:

npm run lambda-local

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.

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

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

Create ~/.aws/credentials:

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

• 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 on GitHub Pages for public access.
  • See GitHub Pages documentation for setup instructions.

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

MIT