aws-lambda-devkit 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,400 @@
+# Getting started
+
+This guide walks you from zero to a working local Lambda invoke. You only need basic Node.js knowledge.
+
+**Time:** about 15 minutes  
+**Goal:** run `lamkit test` and see CloudWatch-style logs on your machine
+
+| | |
+|---|---|
+| Install | `npm install -D aws-lambda-devkit` |
+| Run CLI | `npx lamkit test` |
+| Import in config | `import { defineConfig } from 'aws-lambda-devkit'` |
+
+---
+
+## What problem does this solve?
+
+In production, AWS Lambda runs your `handler` when an event arrives (SQS message, HTTP request, etc.). To test changes locally you could:
+
+- Write huge JSON event files by hand
+- Deploy to dev for every small change
+- Run a heavy emulator stack
+
+Lambda DevKit gives you a lighter path:
+
+1. You keep **one** `handler` export — the same code you deploy
+2. You add a small **`lamkit.config.js`**
+3. You run **`lamkit test --data '{"id":"1"}'`** and lamkit builds a realistic event for you
+
+No changes inside your handler. No deploy required for the basic loop.
+
+---
+
+## What Lambda DevKit does and does not do
+
+| Does | Does not |
+|------|----------|
+| Invoke `handler` locally | Deploy Lambdas |
+| Build SQS / HTTP / SNS shaped events | Create SQS queues or SNS topics |
+| Print START / END / REPORT logs | Replace SAM or CDK |
+| Optionally send/listen on **existing** dev queues | Modify your production handler code |
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| Node.js | Version 20 or newer (`node -v`) |
+| npm | Comes with Node |
+| A handler | Or you will create one in Step 3 |
+
+**Optional packages** (install only when needed):
+
+```bash
+npm install -D tsx                      # TypeScript handler or lamkit.config.ts
+npm install -D @aws-sdk/client-sqs      # lamkit send sqs / lamkit listen
+npm install -D @aws-sdk/client-sns      # lamkit send sns
+```
+
+---
+
+## Step 1 — Create a project folder
+
+You can use an existing Lambda repo or a new folder:
+
+```bash
+mkdir my-lambda-worker
+cd my-lambda-worker
+npm init -y
+```
+
+Your folder will grow to look like this:
+
+```
+my-lambda-worker/
+├── package.json
+├── lamkit.config.js      ← created in Step 2
+├── .env                  ← copy from .env.example
+├── .env.example
+├── events/
+│   └── sample.json
+└── src/
+    └── lambda/
+        └── handler.js    ← created in Step 3
+```
+
+---
+
+## Step 2 — Install the npm package
+
+Package name on npm is **`aws-lambda-devkit`** (CLI command is still **`lamkit`**).
+
+```bash
+npm install -D aws-lambda-devkit
+```
+
+Verify the CLI is available:
+
+```bash
+npx lamkit --help
+```
+
+### Add npm scripts (recommended)
+
+Edit `package.json`:
+
+```json
+{
+  "name": "my-lambda-worker",
+  "type": "module",
+  "scripts": {
+    "test:lambda": "lamkit test",
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "aws-lambda-devkit": "^0.1.0"
+  }
+}
+```
+
+Or scaffold everything with:
+
+```bash
+npx lamkit init --yes
+```
+
+---
+
+## Step 3 — Scaffold config and env files
+
+```bash
+npx lamkit init
+cp .env.example .env
+```
+
+**`lamkit.config.js`** (created for you):
+
+```js
+export default {
+  functions: [
+    {
+      name: 'worker',
+      entry: './src/lambda/handler.js',
+      trigger: 'sqs',
+    },
+  ],
+};
+```
+
+**`.env.example`** (minimal):
+
+```env
+AWS_REGION=us-east-1
+
+# Only needed for lamkit send / lamkit listen
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+```
+
+For `lamkit test` alone, `.env` can stay almost empty. Lamkit loads it automatically if present.
+
+---
+
+## Step 4 — Write your handler
+
+Create **`src/lambda/handler.js`**:
+
+```js
+/**
+ * Production handler — deploy this same file (or its compiled output).
+ * Do NOT import aws-lambda-devkit here.
+ */
+export const handler = async (event, context) => {
+  console.log('RequestId:', context.awsRequestId);
+  console.log('Record count:', event.Records?.length ?? 0);
+
+  for (const record of event.Records ?? []) {
+    const body = JSON.parse(record.body);
+    console.log('Processing message:', body);
+    // your business logic here
+  }
+
+  // SQS handlers often return nothing or partial batch failures:
+  // return { batchItemFailures: [{ itemIdentifier: 'message-id' }] };
+};
+```
+
+**Important rules:**
+
+| Rule | Why |
+|------|-----|
+| Export must be named `handler` (or default export) | Lamkit looks for this symbol |
+| Same file you deploy | Avoids "works locally, different in AWS" |
+| No `aws-lambda-devkit` import in handler | Handler stays production-pure |
+
+---
+
+## Step 5 — Run your first test
+
+```bash
+npx lamkit test --data '{"orderId":"ord_123","amount":42}'
+```
+
+Because you have only one function, the name `worker` is optional.
+
+### What you should see
+
+```
+✓ worker (sqs) — 12ms
+
+Logs:
+START RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479 Version: $LATEST
+RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
+Record count: 1
+Processing message: { orderId: 'ord_123', amount: 42 }
+END RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
+REPORT RequestId: f47ac10b-58cc-4372-a567-0e02b2c3d479  Duration: 12.00 ms  ...
+```
+
+The green `✓` line means lamkit loaded your handler and the invoke finished without an uncaught error.
+
+### What lamkit built for you
+
+With `trigger: 'sqs'`, your `--data` JSON becomes the **body** of an SQS record inside a full `SQSEvent`:
+
+```json
+{
+  "Records": [
+    {
+      "messageId": "...",
+      "body": "{\"orderId\":\"ord_123\",\"amount\":42}",
+      "eventSource": "aws:sqs",
+      "awsRegion": "us-east-1"
+    }
+  ]
+}
+```
+
+Preview without invoking:
+
+```bash
+npx lamkit test --dry-run --data '{"orderId":"ord_123"}'
+```
+
+---
+
+## Step 6 — Use a payload file
+
+Create **`events/order-created.json`**:
+
+```json
+{
+  "orderId": "ord_456",
+  "customerId": "cust_789",
+  "lines": [{ "sku": "ITEM-1", "qty": 2 }]
+}
+```
+
+Run:
+
+```bash
+npx lamkit test --data-file events/order-created.json
+# equivalent:
+npx lamkit test --data @events/order-created.json
+```
+
+---
+
+## Step 7 — Inspect configuration
+
+```bash
+npx lamkit list
+npx lamkit config worker
+```
+
+Use this when env vars or queue URLs do not resolve the way you expect.
+
+---
+
+## Step 8 — Debug with breakpoints (optional)
+
+### VS Code
+
+`lamkit init` creates **`.vscode/launch.json`**. Open the Run and Debug panel and start **"lamkit test (inspect)"**.
+
+### Terminal
+
+```bash
+npx lamkit test --inspect-brk --data '{"orderId":"1"}'
+```
+
+Attach your debugger to the Node process (or use Chrome at `chrome://inspect`).
+
+Set a breakpoint inside `handler` and step through your code.
+
+---
+
+## How the pieces fit together
+
+```
+┌─────────────────┐
+│ lamkit.config.js │  names, entry path, trigger, queue URLs
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  .env (optional) │  AWS_REGION, secrets, queue URLs
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  lamkit test    │  builds event from --data / --event / config
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  your handler   │  export const handler = async (event) => ...
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  console output │  START, your logs, END, REPORT
+└─────────────────┘
+```
+
+**Offline path (`lamkit test`):** no AWS network calls from lamkit itself.  
+**Online path (`send` / `listen`):** optional; see [Recipes — Real SQS](recipes.md#recipe-12--real-sqs-send-then-listen-locally).
+
+---
+
+## When you already have a compiled `dist/` folder
+
+Many teams deploy `./dist/handler.js` after TypeScript compile. Point `entry` at dist:
+
+```js
+export default {
+  functions: [
+    {
+      name: 'worker',
+      entry: './dist/handler.js',
+      trigger: 'sqs',
+    },
+  ],
+};
+```
+
+Workflow:
+
+```bash
+npm run build
+npx lamkit test --data '{"id":"1"}'
+```
+
+---
+
+## Default payload in config
+
+Avoid typing `--data` every time:
+
+```js
+export default {
+  functions: [
+    {
+      name: 'worker',
+      entry: './src/lambda/handler.js',
+      trigger: 'sqs',
+      test: {
+        data: { type: 'PING', source: 'local' },
+      },
+    },
+  ],
+};
+```
+
+```bash
+npx lamkit test
+```
+
+---
+
+## Common first-day mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `Handler entry not found` | Run `npm run build` or fix `entry` path |
+| `must export a named "handler"` | Add `export const handler = ...` |
+| Running from wrong directory | `cd` to folder with `lamkit.config.js` or use `--cwd` |
+| Empty `event.Records` | Set `trigger: 'sqs'` (default) for queue handlers |
+| Expecting lamkit to create queues | You supply existing `queueUrl` for send/listen |
+| Handler works in AWS but not locally | Missing `.env` vars or wrong `entry` (src vs dist) |
+
+More fixes: [Troubleshooting](troubleshooting.md)
+
+---
+
+## Where to go next
+
+| I want to… | Read |
+|------------|------|
+| Every CLI flag with examples | [Commands reference](commands.md) |
+| All config fields explained | [Configuration reference](configuration.md) |
+| Monorepo, TypeScript, real SQS, HTTP, CI | [Recipes](recipes.md) |
+| Fix an error | [Troubleshooting](troubleshooting.md) |