# Recipes

Copy-paste **end-to-end** setups. Each recipe includes folder layout, config, handler snippets, commands, and what to expect.

Replace generic names (`worker`, `WORKER_QUEUE_URL`, etc.) with your own.

**Index**

| # | Scenario |
|---|----------|
| [1](#recipe-1--single-sqs-worker-javascript) | Single SQS worker, plain JavaScript |
| [2](#recipe-2--compiled-typescript-dist) | Compiled TypeScript (`dist/`) |
| [3](#recipe-3--typescript-with-tsx-no-build) | TypeScript live via `tsx` |
| [4](#recipe-4--default-payload-in-config) | Default payload in config |
| [5](#recipe-5--payload-from-a-file) | Payload from JSON file |
| [6](#recipe-6--raw-captured-aws-event) | Raw captured AWS event |
| [7](#recipe-7--sqs-batch-multiple-records) | SQS batch (multiple records) |
| [8](#recipe-8--http-api-gateway-handler) | HTTP / API Gateway handler |
| [9](#recipe-9--sns-trigger-simulated) | SNS trigger (simulated) |
| [10](#recipe-10--monorepo-shared-root-env) | Monorepo + shared root `.env` |
| [11](#recipe-11--asset-links-for-contractsjson) | Asset links for `contracts/*.json` |
| [12](#recipe-12--real-sqs-send--listen-loop) | Real SQS send + listen loop |
| [13](#recipe-13--fifo-queue) | FIFO queue |
| [14](#recipe-14--sns-publish-real-aws) | SNS publish (real AWS) |
| [15](#recipe-15--json-structured-logs) | JSON structured logs |
| [16](#recipe-16--debug-with-breakpoints) | Debug with breakpoints |
| [17](#recipe-17--ci-smoke-test) | CI smoke test (no AWS) |
| [18](#recipe-18--sqs-partial-batch-failures) | SQS partial batch failures |
| [19](#recipe-19--multiple-functions) | Multiple functions |
| [20](#recipe-20--custom-aws-endpoint) | Custom AWS-compatible endpoint |
| [21](#recipe-21--per-invoke-env-overrides) | Per-invoke env overrides |
| [22](#recipe-22--reload-after-code-change) | Reload after code change |

---

## Recipe 1 — Single SQS worker (JavaScript)

**Goal:** Fastest possible setup — no TypeScript, no build step.

**Layout:**

```
order-worker/
├── package.json
├── lamkit.config.js
├── .env
└── src/
    └── handler.js
```

**`package.json`:**

```json
{
  "name": "order-worker",
  "type": "module",
  "scripts": {
    "test:lambda": "lamkit test"
  },
  "devDependencies": {
    "aws-lambda-devkit": "^0.1.0"
  }
}
```

**`src/handler.js`:**

```js
export const handler = async (event) => {
  for (const record of event.Records) {
    const order = JSON.parse(record.body);
    console.log('Processing order', order.orderId);
    if (!order.orderId) throw new Error('orderId required');
  }
};
```

**`lamkit.config.js`:**

```js
export default {
  functions: [
    {
      name: 'worker',
      entry: './src/handler.js',
      trigger: 'sqs',
      test: { data: { orderId: 'ord_local_1', amount: 10 } },
    },
  ],
};
```

**Commands:**

```bash
npm install
npx lamkit init    # optional if you already have config
npx lamkit test
npx lamkit test --data '{"orderId":"ord_999","amount":50}'
```

**Expect:** `✓ worker (sqs)` and logs showing your `orderId`.

---

## Recipe 2 — Compiled TypeScript (`dist/`)

**Goal:** Match production — deploy `dist/`, test `dist/`.

**Layout:**

```
order-worker/
├── lamkit.config.js
├── src/handler.ts
├── dist/handler.js      ← npm run build
└── tsconfig.json
```

**`src/handler.ts`:**

```ts
import type { SQSEvent, SQSHandler } from 'aws-lambda';

export const handler: SQSHandler = async (event: SQSEvent) => {
  for (const record of event.Records) {
    const body = JSON.parse(record.body);
    console.log('Typed handler:', body);
  }
};
```

**`lamkit.config.js`:**

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

**Commands:**

```bash
npm run build
npx lamkit test --data '{"orderId":"1"}'
```

**Tip:** Add `"test:lambda": "npm run build && lamkit test"` to run build before every test.

---

## Recipe 3 — TypeScript with `tsx` (no build)

**Goal:** Iterate on `.ts` without compiling each time.

```bash
npm install -D aws-lambda-devkit tsx
```

**`lamkit.config.js`:**

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

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

Lamkit uses the `tsx` peer to import `.ts` directly when `dist/` is missing.

---

## Recipe 4 — Default payload in config

**Goal:** Run `lamkit test` with no CLI arguments.

```js
export default {
  functions: [
    {
      name: 'worker',
      entry: './src/handler.js',
      trigger: 'sqs',
      test: {
        data: {
          type: 'PING',
          timestamp: '2026-01-15T12:00:00Z',
        },
      },
    },
  ],
};
```

```bash
npx lamkit test
```

CLI `--data` still overrides config when provided.

---

## Recipe 5 — Payload from a file

**`events/order-created.json`:**

```json
{
  "orderId": "ord_123",
  "customerId": "cust_456",
  "lines": [
    { "sku": "WIDGET-A", "quantity": 2, "price": 19.99 }
  ]
}
```

```bash
npx lamkit test --data-file events/order-created.json
npx lamkit test --data @events/order-created.json
```

Good for large payloads you do not want inline in the shell.

---

## Recipe 6 — Raw captured AWS event

**Goal:** Test with the **exact** event shape from production.

1. Copy an event from CloudWatch Logs or AWS documentation.
2. Save as **`events/sqs-production-sample.json`** (full `SQSEvent` with `Records` array).
3. Run:

```bash
npx lamkit test --event events/sqs-production-sample.json
```

This skips the event builder — useful when field names or attributes must match production exactly.

---

## Recipe 7 — SQS batch (multiple records)

**Goal:** Test batch handling and partial failure logic.

**Handler example:**

```js
export const handler = async (event) => {
  const failures = [];
  for (const record of event.Records) {
    try {
      const body = JSON.parse(record.body);
      if (body.shouldFail) throw new Error('simulated failure');
    } catch {
      failures.push({ itemIdentifier: record.messageId });
    }
  }
  return { batchItemFailures: failures };
};
```

**Commands:**

```bash
# One payload → 5 records
npx lamkit test --data '{"id":"1"}' --batch-size 5

# Array → one record per element
npx lamkit test --data '[{"id":"1"},{"id":"2"},{"id":"3"}]'

# Fail CI if batchItemFailures returned
npx lamkit test --strict-batch --data '[{"shouldFail":true}]'
```

---

## Recipe 8 — HTTP (API Gateway) handler

**`src/http.js`:**

```js
export const handler = async (event) => {
  const body = event.body ? JSON.parse(event.body) : {};
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ greeting: `Hello, ${body.name ?? 'world'}` }),
  };
};
```

**`lamkit.config.js`:**

```js
export default {
  functions: [
    {
      name: 'api',
      entry: './src/http.js',
      trigger: 'http',
      test: { data: { name: 'Ada' } },
    },
  ],
};
```

```bash
npx lamkit test api
npx lamkit test api --data '{"name":"Bob"}'
```

---

## Recipe 9 — SNS trigger (simulated)

**`lamkit.config.js`:**

```js
export default {
  functions: [
    {
      name: 'subscriber',
      entry: './dist/handler.js',
      trigger: 'sns',
      test: { data: { metric: 'cpu', value: 95, threshold: 90 } },
    },
  ],
};
```

**Handler:**

```js
export const handler = async (event) => {
  for (const record of event.Records) {
    const message = JSON.parse(record.Sns.Message);
    console.log('Alert:', message);
  }
};
```

```bash
npx lamkit test subscriber
```

---

## Recipe 10 — Monorepo with shared root `.env`

**Goal:** Lambda package in `packages/worker/` but secrets in repo root `.env`.

**Layout:**

```
acme-platform/
├── .env
└── packages/
    └── order-worker/
        ├── lamkit.config.mjs
        ├── dist/handler.js
        └── package.json
```

**Root `.env`:**

```env
AWS_REGION=eu-west-1
WORKER_QUEUE_URL=https://sqs.eu-west-1.amazonaws.com/111222333/acme-dev-orders
APP_DB_NAME=orders_dev
APP_DB_PORT=5432
```

**`packages/order-worker/lamkit.config.mjs`:**

```js
import { loadProjectEnv } from 'aws-lambda-devkit';

loadProjectEnv({
  files: ['../../.env'],
  skipDotenv: true,
  aliases: {
    APP_DB_NAME: 'DB_NAME',
    APP_DB_PORT: 'DB_PORT',
  },
});

const region = process.env.AWS_REGION ?? 'eu-west-1';

export default {
  defaults: { aws: { region } },
  functions: [
    {
      name: 'worker',
      entry: './dist/handler.js',
      trigger: 'sqs',
      aws: { queueUrl: process.env.WORKER_QUEUE_URL, region },
    },
  ],
};
```

```bash
cd packages/order-worker
npm install -D aws-lambda-devkit
npx lamkit test --data '{"orderId":"1"}'
```

---

## Recipe 11 — Asset links for `contracts/*.json`

**Goal:** `dist/` code does `require('../../contracts/abi.json')` but files live in `src/contracts/`.

**Layout:**

```
worker/
├── src/contracts/abi.json
├── dist/handler.js
└── lamkit.config.js
```

**`lamkit.config.js`:**

```js
export default {
  assetLinks: [{ path: 'contracts', target: 'src/contracts' }],
  functions: [
    { name: 'worker', entry: './dist/handler.js', trigger: 'sqs' },
  ],
};
```

Lamkit creates `contracts → src/contracts` symlink before invoke if `contracts/` is missing.

---

## Recipe 12 — Real SQS: send then listen locally

**Goal:** End-to-end with a real dev queue; handler runs on your machine.

**Install:**

```bash
npm install -D @aws-sdk/client-sqs
```

**`.env`:**

```env
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
WORKER_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/123456789012/acme-dev-orders
```

**`lamkit.config.js`:**

```js
export default {
  defaults: { aws: { region: process.env.AWS_REGION } },
  functions: [
    {
      name: 'worker',
      entry: './dist/handler.js',
      trigger: 'sqs',
      aws: { queueUrl: process.env.WORKER_QUEUE_URL },
    },
  ],
};
```

**Terminal 1 — listener:**

```bash
npx lamkit listen worker
```

**Terminal 2 — sender:**

```bash
npx lamkit send sqs worker --data '{"orderId":"live-1"}'
```

**Expect:** Terminal 1 prints `message <id>: success` and your handler logs.

**Safety:** Use a dev-only queue. Disable the deployed Lambda event source mapping while listening.

**One-shot:**

```bash
npx lamkit send sqs worker --data '{"orderId":"1"}'
npx lamkit listen worker --once --expect-messages
```

---

## Recipe 13 — FIFO queue

Same as Recipe 12, but `WORKER_QUEUE_URL` ends with `.fifo`:

```env
WORKER_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/123456789012/acme-orders.fifo
```

```bash
npx lamkit send sqs worker --data '{"orderId":"1","group":"customer-A"}'
```

Lamkit sets `MessageGroupId` and `MessageDeduplicationId` automatically.

---

## Recipe 14 — SNS publish (real AWS)

```bash
npm install -D @aws-sdk/client-sns
```

```env
EVENTS_TOPIC_ARN=arn:aws:sns:us-east-1:123456789012:acme-dev-events
```

```js
export default {
  functions: [
    {
      name: 'notifier',
      entry: './dist/handler.js',
      trigger: 'sns',
      aws: { topicArn: process.env.EVENTS_TOPIC_ARN },
    },
  ],
};
```

```bash
npx lamkit send sns notifier --data '{"event":"ORDER_PLACED","orderId":"1"}'
```

To invoke the handler offline with SNS event shape, use `lamkit test` with `trigger: 'sns'`.

---

## Recipe 15 — JSON structured logs

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

```bash
npx lamkit test --data '{"id":"1"}' | jq .
```

Each log line is a JSON object — easier for scripts and log aggregators locally.

---

## Recipe 16 — Debug with breakpoints

**VS Code:** Run **"lamkit test (inspect)"** from `.vscode/launch.json` (created by `lamkit init`).

**Terminal:**

```bash
npx lamkit test worker --inspect-brk --data '{"orderId":"1"}'
```

Set breakpoints in your handler, attach debugger, step through code.

---

## Recipe 17 — CI smoke test

**Goal:** GitHub Actions / GitLab CI runs handlers without AWS credentials.

**`package.json`:**

```json
{
  "scripts": {
    "test:lambda": "lamkit test --all"
  }
}
```

**Config** — each function needs `test.data` or handlers must tolerate empty events:

```js
export default {
  functions: [
    {
      name: 'worker',
      entry: './dist/handler.js',
      trigger: 'sqs',
      test: { data: { type: 'CI_PING' } },
    },
  ],
};
```

**CI step:**

```yaml
- run: npm ci
- run: npm run build
- run: npm run test:lambda
```

Handlers that call AWS/DB in CI may need mocks or `--dry-run` only.

---

## Recipe 18 — SQS partial batch failures

```bash
npx lamkit test worker --strict-batch --data '[{"id":"ok"},{"id":"bad"}]'
```

Exit code `1` if handler returns:

```js
return {
  batchItemFailures: [{ itemIdentifier: 'message-id-here' }],
};
```

Useful in shell scripts and CI gates.

---

## Recipe 19 — Multiple functions

```js
export default {
  functions: [
    {
      name: 'orders',
      entry: './dist/orders.js',
      trigger: 'sqs',
      test: { data: { type: 'ORDER' } },
    },
    {
      name: 'billing',
      entry: './dist/billing.js',
      trigger: 'sqs',
      test: { data: { type: 'INVOICE' } },
    },
  ],
};
```

```bash
npx lamkit list
npx lamkit test orders
npx lamkit test billing
npx lamkit test --all
```

---

## Recipe 20 — Custom AWS-compatible endpoint

```env
AWS_ENDPOINT_URL=https://internal-gateway.example.com
AWS_REGION=us-east-1
```

```js
export default {
  defaults: {
    aws: {
      region: process.env.AWS_REGION,
      endpoint: process.env.AWS_ENDPOINT_URL,
    },
  },
  functions: [/* ... */],
};
```

When using real IAM keys (`AKIA*`), `loadProjectEnv()` strips endpoint overrides by default so SDK hits real AWS. Set `stripCustomEndpointForRealAws: false` to keep custom endpoints with real keys.

---

## Recipe 21 — Per-invoke env overrides

```bash
npx lamkit test worker \
  --env FEATURE_NEW_PARSER=true \
  --env LOG_LEVEL=debug \
  --data '{"orderId":"1"}'
```

Does not modify `.env` — only the current process.

---

## Recipe 22 — Reload after code change

During a tight edit-test loop:

```bash
# terminal 1: edit src/handler.js
npx lamkit test worker --reload --data '{"orderId":"1"}'
```

`--reload` bypasses the handler module cache so you see fresh code without restarting the shell.

---

## Picking a recipe

| Your situation | Start with |
|----------------|------------|
| Brand new project | Recipe 1 |
| TypeScript + `tsc` | Recipe 2 |
| Monorepo | Recipe 10 |
| `require('../../contracts/...')` fails | Recipe 11 |
| Test against real dev queue | Recipe 12 |
| GitHub Actions | Recipe 17 |

More detail: [Configuration](configuration.md) · [Commands](commands.md) · [Troubleshooting](troubleshooting.md)