{"id":13727035,"url":"https://github.com/teamplanes/cdk-watch","last_synced_at":"2026-01-19T20:04:32.264Z","repository":{"id":45958632,"uuid":"337503675","full_name":"teamplanes/cdk-watch","owner":"teamplanes","description":"A CLI to watch and live-update your CDK Stack's Lambdas","archived":false,"fork":false,"pushed_at":"2022-03-29T20:33:32.000Z","size":1189,"stargazers_count":110,"open_issues_count":5,"forks_count":6,"subscribers_count":7,"default_branch":"next","last_synced_at":"2024-11-14T17:47:54.899Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teamplanes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-09T18:48:31.000Z","updated_at":"2024-01-31T22:31:45.000Z","dependencies_parsed_at":"2022-08-28T20:21:17.527Z","dependency_job_id":null,"html_url":"https://github.com/teamplanes/cdk-watch","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teamplanes%2Fcdk-watch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teamplanes%2Fcdk-watch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teamplanes%2Fcdk-watch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teamplanes%2Fcdk-watch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teamplanes","download_url":"https://codeload.github.com/teamplanes/cdk-watch/tar.gz/refs/heads/next","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252965181,"owners_count":21832835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:03:36.612Z","updated_at":"2026-01-19T20:04:32.235Z","avatar_url":"https://github.com/teamplanes.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# `cdk-watch` 👀\n\n\u003e Run your CDK Stack's Lambda functions as if they were in a development environment.\n\n- As simple as `cdkw \"MyApp/MyApi/**\"`\n- Your code will be watched and built with the same esbuild config as when deploying your stack\n- Simply switch-out your existing `NodejsFunction` with the `WatchableNodejsFunction` construct\n- Opt-in to real-time logs, so no more digging through CloudWatch to find your Lambda's logs\n- Load your node modules as a separate lambda layer (allows for faster build/upload times)\n- Written in TypeScript\n- No extra infrastructure required, unless you are opting-in to real-time logs\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://cdk-watch-static.s3.eu-west-2.amazonaws.com/demo.gif\" width=\"500\"\u003e\n\u003c/div\u003e\n\n---\n\n## Getting Started\n\n#### 1. CDK Updates\n\nSimply switch to use the `WatchableNodejsFunction` rather than the `NodejsFunction`.\n```patch\n- import {NodejsFunction} from '@aws-cdk/aws-lambda-nodejs';\n+ import {WatchableNodejsFunction} from 'cdk-watch';\n\n// ...\n\n- const lambda = new NodejsFunction(this, 'Lambda', {\n+ const lambda = new WatchableNodejsFunction(this, 'Lambda', {\n  entry: path.resolve(__dirname, '../src/my-lambda.ts'),\n  handler: 'handler',\n});\n```\n\n#### 2. Run Your Stack\n\n```sh\n# Run all Lambda functions\n$ yarn cdkw \"**\"\n\n# Run just your API Lambdas, for example\n$ yarn cdkw \"MyStack/API/**\"\n\n# Run without logs\n$ yarn cdkw \"MyStack/API/**\" --no-logs\n\n# Pass context to synth\n$ yarn cdkw \"MyStack/API/**\" -c foo=bar -c hello=world\n\n# If you are using npm\n$ npm run cdkw \"**\"\n```\n\n*Skip to the [command reference](#command-reference).*\n\n---\n\n## Real-time Logs\n\n`cdk-watch` provides real-time logs over web-sockets to make the development\nfeedback-loop faster when debugging your lambdas. This is an additional feature\nthat requires opt-in, and you have two options for achieving this.\n1. **Turn on for all Lambdas:** To turn on real-time logging by default for all\n   watchable lambdas in your stack you can set the context variable\n   `cdk-watch:forceRealTimeLoggingEnabled` to `true`.\n2. To set an individual Lambda to support real-time logging you can pass a prop\n   to the `WatchableNodejsFunction`: `watchOptions.realTimeLoggingEnabled=true`.\n\n### How does real-time logging work?\n\nWhen deploying your stack the `WatchableNodejsFunction` will include the\nnecessary infrastructure to support WebSockets via API Gateway. It'll also\nassign a Lambda Layer Extension to wrap your lambda, the wrapper will patch the\n`console` and forward all logs to all API Gateway connections. If you have\nmultiple lambdas in your stack it'll only create the require infrastructure\nonce, and reuse it for all lambdas that need it.\n\n## Node Modules Layer\n\nCDK-Watch allows you to install your node-modules as a stand alone layer. This\nmeans that when you deploy, `cdk-watch` will install your modules in a separate\nasset and install them as the lambda's layer. This is great for dev-performance\nas the upload bundle will be much smaller. You can configure this using the\n`bundling.nodeModulesLayer` property:\n\n```ts\nbundling: {\n  // Install only \"knex\" as a standalone layer\n  nodeModulesLayer: {include: ['knex']}\n}\n```\n\nOR:\n\n```ts\nbundling: {\n  // Install every module found in your package.json except \"knex\"\n  nodeModulesLayer: {exclude: ['knex']}\n}\n```\n\n## How, what \u0026 why?\n\n### Why would you want to do this?\n\n- Deploying via CDK is slow, it takes 1 minute to release an update to a\n  zero-dependency, 1 line Lambda function\n- AWS provides a tonne of great services, therefore running your code and CDK\n  Stack on AWS when developing makes sense rather than attempting to fully\n  replicate the environment locally, or missing out on using some of it's services\n- Provided you keep your Lambda's small, an update via `cdk-watch` will take a\n  couple of seconds\n\n### How does it work?\n\n1. `cdkw` will run `cdk synth`\n2. At synthesis the `WatchableNodejsFunction` construct will write a manifest\n   file including Lambda Logical IDs, their Stack names and their esbuild config\n3. The CLI will now read the manifest and make API calls to fetch the Physical\n   IDs of the lambdas\n4. The CLI will start polling the logs of each Lambda\n5. The CLI will now start esbuild in `watch` mode for each Lambda\n6. When the code successfully rebuilds it Zips and uploads the output to Lambda\n   directly by calling `updateFunctionCode`\n\n### How is this different from [Serverless-Stack](https://github.com/serverless-stack/serverless-stack)?\n\nSST runs your Lambda functions locally by mocking the deployed lambda with your\nlocal environment. It comes with a number of performance benefits due to the\nfact that it doesn't need to upload your function code every time it change.\nThat said, `cdk-watch` does not come with a slow feedback loop, you can expect\n1s-5s from the moment you save a file to the moment its available on AWS. The\nupside of `cdk-watch` is we deploy no extra infrastructure to facilitate the\ndevelopment environment so there is less discrepancy between prod and pre-prod\nenvironments.\n\n---\n\n## Command Reference\n\nFor more info on each command add a `--help` flag after any one of them.\n\n- **Watch:** `cdkw \"**\"` watch your Lambda where the CDK construct path matches\n  the glob\n- **List:** `cdkw ls \"**\"` lists all your available `WatchableNodejsFunction`\n  Constructs, a convenience command to help you get find paths you need\n- **Once:** `cdkw once \"**\"` updates your lambda's once, rather than in watch\n- **Logs:** `cdkw logs \"**\"` just tails logs for each of the matching lambdas\n\n---\n\n✈️ / [planes.studio](https://planes.studio)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteamplanes%2Fcdk-watch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteamplanes%2Fcdk-watch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteamplanes%2Fcdk-watch/lists"}