Lambda DevKit

Test AWS Lambda handlers locally — same handler export, realistic events, CloudWatch-style logs. Optional real SQS/SNS against a dev account.

| | Name | |---|------| | Repository | github.com/asimsheikh12/lambda-devkit | | npm package | aws-lambda-devkit | | CLI command | lamkit | | Config file | lamkit.config.js (also .mjs, .cjs, .ts) |

Install as a dev dependency. Complements SAM, CDK, and SST; does not deploy infrastructure.

Documentation

New here? Start with the guides below. They use plain language and generic examples only.

| Guide | Description | |-------|-------------| | Getting started | Install → first successful lamkit test (~15 min walkthrough with sample output) | | Commands reference | Every CLI command and flag with copy-paste examples | | Configuration reference | Every config field, loadProjectEnv, assetLinks, full examples | | Recipes | 22 end-to-end setups with layouts, handlers, commands, and expected results | | Troubleshooting | Symptom → cause → fix for common errors |

What this package does

| Feature | Command | Needs AWS? | |---------|---------|------------| | Simulate invoke | lamkit test | No | | List / inspect config | lamkit list, lamkit config | No | | Send message to SQS | lamkit send sqs | Yes | | Poll SQS → local handler | lamkit listen | Yes | | Publish to SNS | lamkit send sns | Yes | | Scaffold project files | lamkit init | No |

What it does not do

• Deploy Lambdas or create queues/topics
• Replace SAM Docker emulation or full IaC workflows
• Require changes inside your production handler code

Five-minute quick start

npm install -D aws-lambda-devkit
npx lamkit init
cp .env.example .env

Create src/lambda/handler.js:

export const handler = async (event) => {
  console.log(event);
  return { ok: true };
};

lamkit.config.js (created by init):

export default {
  functions: [
    {
      name: 'worker',
      entry: './src/lambda/handler.js',
      trigger: 'sqs',
    },
  ],
};

Run:

npx lamkit test --data '{"id":"1"}'

You should see START, your logs, END, and REPORT lines.

Next: Getting started · Recipes

Config at a glance

export default {
  defaults: {
    runtime: 'nodejs20.x',
    memorySize: 512,
    timeout: 30,
    logFormat: 'text',
    aws: { region: 'us-east-1' },
  },
  assetLinks: [
    { path: 'contracts', target: 'src/contracts' },
  ],
  functions: [
    {
      name: 'worker',
      entry: './dist/handler.js',
      trigger: 'sqs',
      aws: { queueUrl: process.env.WORKER_QUEUE_URL },
      test: { data: { id: '1' } },
    },
  ],
};

| Block | Purpose | |-------|---------| | defaults | Shared memory, timeout, region, log format | | assetLinks | Symlink local asset folders before invoke (see docs) | | functions | One entry per Lambda; entry must export handler |

Monorepo / shared .env: call loadProjectEnv() at the top of your config — example in recipes.

Config file names: lamkit.config.{js,mjs,cjs,ts} (.ts needs optional tsx peer).

Commands

Daily development

lamkit test [name] --data '{"key":"value"}'
lamkit test --data-file events/payload.json
lamkit test --event events/captured-sqs.json
lamkit test --all
lamkit test --all --parallel
lamkit test --inspect-brk
lamkit list
lamkit config [name]

Real AWS (dev account only)

npm install -D @aws-sdk/client-sqs   # for send/listen
lamkit send sqs worker --data '{"id":"1"}'
lamkit listen worker --once

Use a dev queue — do not run listen against production while deployed Lambdas consume the same queue.

Full command reference: Commands

Optional peers

| Install when… | Package | |---------------|---------| | TypeScript handler or lamkit.config.ts | tsx | | lamkit send sqs / lamkit listen | @aws-sdk/client-sqs | | lamkit send sns | @aws-sdk/client-sns |

Default install is 4 small runtime dependencies (~0.2 MB unpacked): zod, commander, picocolors, @types/aws-lambda.

Triggers (simulated lamkit test)

| trigger | Event type | |-----------|------------| | sqs | SQS (default) | | http | API Gateway HTTP | | sns | SNS notification | | s3 | S3 object event | | eventbridge | EventBridge | | schedule | Scheduled / cron |

Examples per trigger: Recipes

vs SAM / SST

| Tool | Best for | |------|----------| | Lambda DevKit | Fast edit-test loop on Node handlers; optional real SQS poll | | SAM | Docker parity, deploy, broader AWS emulation | | SST dev | Live AWS proxy tied to SST stacks |

Programmatic API

import {
  defineConfig,
  loadProjectEnv,
  buildSqsEvent,
  ensureAssetLinks,
} from 'aws-lambda-devkit';

// Types only (no runtime import):
import type { FunctionConfig, LamkitConfigInput } from 'aws-lambda-devkit/config';

Use defineConfig() in lamkit.config.ts so every config field shows docs on hover. Most users only need the CLI and lamkit.config.*.

License

MIT