aws-cdk-local-lambda

Run your CDK API Gateway + Lambda stack locally over HTTP - no mocks, no handler registry. Reads cdk synth output directly and boots a local Express server that mirrors your deployed routes, with hot reload.

Built with

---

Why this exists

Iterating on a CDK-deployed API usually means waiting for cdk deploy, or wiring up SAM/LocalStack with a handler registry that drifts from your real stack. aws-cdk-local-lambda skips all of that:

• Reads cdk synth directly - your stack template is the source of truth.
• Real Express server - no mocks, no registry, no fake invoke.
• Hot reload - handlers re-bundle on save, no process restart.
• Authorizers per route - invoked exactly like API Gateway does.

Install

npm install aws-cdk-local-lambda

or

pnpm add aws-cdk-local-lambda

Quickstart

The recommended setup is a few scripts in your package.json. See the simple-crud example for a complete working setup.

{
  "scripts": {
    "synth": "cdk synth --app 'tsx cdk/app.ts'",
    "extract": "cdk-local extract --cdk-out cdk.out --stack MyStack --stage dev --out .cdk-local/manifest.json",
    "manifest": "npm run synth && npm run extract",
    "serve": "cdk-local serve --manifest .cdk-local/manifest.json --port 3001 --watch",
    "dev": "npm run manifest && npm run serve"
  }
}

Then run:

npm run dev

Note

Add .cdk-local/ or whatever path you choose to your .gitignore - it holds the generated manifest and would be machine-specific.

CLI reference

All-in-one: extract + serve

npx cdk-local dev --cdk-out cdk.out --stack MyStack --stage dev --port 3001

Step 1 - parse cdk.out into a manifest file

npx cdk-local extract --cdk-out cdk.out --stack MyStack --stage dev --out .cdk-local/manifest.json

Step 2 - start the local server from that manifest

npx cdk-local serve --manifest .cdk-local/manifest.json --port 3001 --watch

When to keep them separate: if your handlers don't change between runs, reuse the same manifest and skip re-running cdk synth. Only re-extract when you add or rename a handler - the server hot-reloads handler code on save.

Command	Purpose	Watch default
dev	extract + serve in one step	on (--no-watch to disable)
extract	Parse cdk.out → LocalManifest JSON (pass --synth to run synth)	n/a
serve	Boot Express from a pre-built manifest	opt-in (--watch)

extract options

Flag	Required	Description
--cdk-out <dir>	yes	Path to the cdk.out directory
--stack <name>	yes	CloudFormation stack name
--stage <env>	no	Stage suffix used to strip prefixes from Lambda function names (e.g. dev). Omit if your function names have no stage prefix.
--out <file>	no	Output path for the manifest JSON (default: stdout)
--synth	no	Run cdk synth before extracting
--repo-root <dir>	no	Repo root for resolving handler source paths (default: cwd)
--quiet	no	Suppress framework log output (file changes, module invalidations, etc.)

serve options

Flag	Required	Description
--manifest <file>	yes	Path to a manifest JSON produced by extract
--port <n>	no	Port to listen on (default: 3001)
--watch	no	Enable hot reload on handler file changes
--quiet	no	Suppress framework log output

dev options

Accepts all extract options plus --port, --no-watch, and --quiet.

Contributing

Contributions are welcome - small PRs, clear commits, conventional commits enforced.

• CONTRIBUTING.md - pull request workflow and expectations
• ARCHITECTURE.md - high level overview of what the package does internally

License

MIT © tiny-build

---

This project is not affiliated with, endorsed by, or sponsored by Amazon Web Services (AWS) in any way. AWS, CDK, Lambda, and API Gateway are trademarks of Amazon.com, Inc. or its affiliates. All trademarks and copyrights referenced in this project belong to their respective owners.