CDK: how to run and debug locally without SAM?

[kenberkeley]

Before asking, I searched a lot but only found this related topic:

• Use the SAM CLI to build and test locally - aws-lambda-powertools-typescript/examples/sam

It seems there are no other methods to run / debug the code locally without using SAM, right?

[dreamorosi]

Hi @kenberkeley,

Generally speaking SAM is a good way to run and debug your Lambda functions locally. This is because behind the scenes SAM spins up a docker container and runs your code into an environment that is very close to the one where your function runs on AWS Lambda. This allows you to have confidence that the same packages, file system structure, and environment variables that you'd have on Lambda are also in your local test environment.

This however has a cost in terms of feedback loop and complexity that can vary depending on your machine as spinning a container for each iteration is somewhat resource intensive.

Another option would be to treat your functions as just that, and test/debug them as pure functions. This can be considered a low fidelity test as most of the environment in which your function runs will be different from the one it'll run once deployed. However this type of setup allows you to iterate much faster by simply invoking your function with Node.js and pass it an event.

Both strategies can be valuable and I encourage you to evaluate the trade offs described above and pick the option that is more appropriate for your needs.

An additional note here would be that none of these methods should be considered as a real replacement for tests run on a real AWS environment. This is because there are aspects like IAM permissions, trigger patterns/behaviors, or integration with other services that can't be reliably mocked locally.

[kenberkeley]

Thanks @dreamorosi for your incredibly detailed and patient reply, I appreciate it.

Indeed SAM is a good way to run and debug Lambda functions locally. However, with the presence of CDK (my beloved wife) in my project, SAM is like a redundant mistress/ex-wife 😂 Additionally, we expect that the API can run locally (hot reload please) with a single endpoint (like localhost:8080/api) to facilitate development/debugging/writing E2E tests, etc.

Next, the "same packages, file system structure, and environment variables" benefits you mentioned are manageable and provisionable, which I am not too worried about. Finally, in terms of "integration with other AWS services", we have saml2aws to log in as a developer role.

So I ended up with the following file structure and pattern to ensure fast iteration:

├- src
   ├- app.ts // Expose an Express.js instance
   ├- aws_lambda_entry.ts // CDK's NodejsFunction entry
   ├- local_dev_entry.ts // For local development, use `nodemon` or `tsc-watch` to hot reload

/* app.ts */
import express from "express" // Or you can use Nest.js / routing-controllers
export const app = express()

app.get("/api", (req, res) => {
  res.json({ hello: "world" })
})

/* aws_lambda_entry.ts */
import serverlessExpress from "@vendia/serverless-express" // The key to smooth discrepancies
import { app } from "./app"

export const handler = serverlessExpress({ app })

/* local_dev_entry.ts */
import "dotenv/config" // Loads env vars

import { app } from "./app"

const port = 8080
app.listen(port, async () => {
  console.info(`API is running on port ${port}`)
})

---

Debugging setup tips for VS Code users according to Node.js debugging in VS Code

// .vscode/settings.json
{
  "debug.javascript.autoAttachFilter": "onlyWithFlag"
}

// package.json
"scripts": {
  "dev": "tsc-watch --onSuccess 'node --inspect build/local_dev_entry.js'" // `--inspect` is the flag
}