https://github.com/mrgrain/cdk-updown
Self-executable CDK apps
https://github.com/mrgrain/cdk-updown
automation aws cdk cli
Last synced: 6 months ago
JSON representation
Self-executable CDK apps
- Host: GitHub
- URL: https://github.com/mrgrain/cdk-updown
- Owner: mrgrain
- License: mit
- Created: 2025-06-28T17:15:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-19T00:03:40.000Z (6 months ago)
- Last Synced: 2026-01-19T10:01:15.250Z (6 months ago)
- Topics: automation, aws, cdk, cli
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@mrgrain/cdk-updown
- Size: 1.18 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 
Self-executable CDK apps.
Ever tried to quickly demo some infrastructure code? You write your CDK app, then switch to the terminal for `cdk deploy`, then back again for `cdk destroy`. It's annoying. Sharing examples is even worse - people need the CDK CLI installed and configured just to try your code. CDK up/down fixes this by making your apps self-executable. Your code becomes the deployment tool. One command to deploy and clean up. Perfect for quick prototyping, live demos, and tutorials where you don't want setup friction getting in the way.
## Installation
Install the package using your preferred package manager:
```console
npm install @mrgrain/cdk-updown
yarn add @mrgrain/cdk-updown
pnpm add @mrgrain/cdk-updown
bun add @mrgrain/cdk-updown
```
## Usage
Create an executable TypeScript file for your CDK app `./bin/my-app.ts` using the `updown()` function.
```typescript
import { updown } from "@mrgrain/cdk-updown";
import { App, Stack, aws_sns } from "aws-cdk-lib";
const cli = updown(async () => {
// Build your CDK app here
const app = new App();
const stack = new Stack(app);
new aws_sns.Topic(stack, "Topic");
return app.synth();
});
// Run the CLI
await cli.run();
```
Then execute as usual:
```console
npx tsx ./bin/my-app.ts
```
## Single-file executable
Using a bundle that can produce single-file executables, it is easily possible to make your CDK app fully runtime independent.
For example [with Bun](https://bun.sh/docs/bundler/executables):
```console
bun build ./bin/my-app.ts --compile --minify --outfile ./dist/my-app
```
Now you have a fully self-contained binary of your app:
```console
./dist/my-app
```
## Advanced Use Cases
You can also call `up()` and `down()` directly.
It gives you more control over when to deploy or destroy your infrastructure without relying on command-line arguments.
Both methods return deployment data and throw errors instead of exiting the process.
They skip the selection dialog, but maintain the terminal output.
You can use them to build a more customized CLI experience.
```typescript
import { updown } from "@mrgrain/cdk-updown";
import { App, Stack, aws_sns } from "aws-cdk-lib";
declare const builder: AssemblyBuilder;
try {
// Create the updown cli
const cli = updown(builder);
// Up and get deployment result
const deployResult = await cli.up();
console.log(`Deployed ${deployResult.stacks.length} stacks`);
// Down and get destroy result
const destroyResult = await cli.down();
console.log(`Destroyed ${destroyResult.stacks.length} stacks`);
} catch (error) {
console.error('Operation failed:', error.message);
// Handle error as needed
}
```