/aws-cdk

name: aws-cdk
description: Provides AWS CDK TypeScript patterns for defining, validating, and deploying AWS infrastructure as code. Use when creating CDK apps, stacks, and reusable constructs, modeling serverless or VPC-based architectures, applying IAM and encryption defaults, or testing and reviewing `cdk synth`, `cdk diff`, and `cdk deploy` changes. Triggers include "aws cdk typescript", "create cdk app", "cdk stack", "cdk construct", "cdk deploy", and "cdk test".
allowed-tools: Read, Write, Edit, Bash, Grep, Glob

AWS CDK TypeScript

Overview

Use this skill to build AWS infrastructure in TypeScript with reusable constructs, safe defaults, and a validation-first delivery loop.

When to Use

Use this skill when:

• Creating or refactoring a CDK app, stack, or reusable construct in TypeScript
• Choosing between L1, L2, and L3 constructs
• Building serverless, networking, or security-focused AWS infrastructure
• Wiring multi-stack applications and environment-aware deployments
• Validating infrastructure changes with `cdk synth`, tests, `cdk diff`, and `cdk deploy`

Instructions

1. Project Initialization

# Create a new CDK app
npx cdk init app --language typescript

# Project structure
my-cdk-app/
├── bin/
│   └── my-cdk-app.ts          # App entry point (instantiates stacks)
├── lib/
│   └── my-cdk-app-stack.ts    # Stack definition
├── test/
│   └── my-cdk-app.test.ts     # Tests
├── cdk.json                    # CDK configuration
├── tsconfig.json
└── package.json

2. Core Architecture

import { App, Stack, StackProps, CfnOutput, RemovalPolicy } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

// Define a reusable stack
class StorageStack extends Stack {
  public readonly bucketArn: string;

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const bucket = new s3.Bucket(this, 'DataBucket', {
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      removalPolicy: RemovalPolicy.RETAIN,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
    });

    this.bucketArn = bucket.bucketArn;
    new CfnOutput(this, 'BucketName', { value: bucket.bucketName });
  }
}

// App entry point
const app = new App();

new StorageStack(app, 'DevStorage', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: 'us-east-1' },
  tags: { Environment: 'dev' },
});

new StorageStack(app, 'ProdStorage', {
  env: { account: '123456789012', region: 'eu-west-1' },
  tags: { Environment: 'prod' },
  terminationProtection: true,
});

app.synth();

3. Construct Levels

| Level | Description | Use When | |-------|-------------|----------| | **L1** (`Cfn*`) | Direct CloudFormation mapping, full control | Need properties not exposed by L2 | | **L2** | Curated with sensible defaults and helper methods | Standard resource provisioning (recommended) | | **L3** (Patterns) | Multi-resource architectures | Common patterns like `LambdaRestApi` |

// L1 — Raw CloudFormation
new s3.CfnBucket(this, 'L1Bucket', { bucketName: 'my-l1-bucket' });

// L2 — Sensible defaults + grant helpers
const bucket = new s3.Bucket(this, 'L2Bucket', { versioned: true });
bucket.grantRead(myLambda);

// L3 — Multi-resource pattern
new apigateway.LambdaRestApi(this, 'Api', { handler: myLambda });

4. CDK Lifecycle Commands

cdk synth          # Synthesize CloudFormation template
cdk diff           # Compare deployed vs local changes
cdk deploy         # Deploy stack(s) to AWS
cdk deploy --all   # Deploy all stacks
cdk destroy        # Tear down stack(s)
cdk ls             # List all stacks in the app
cdk doctor         # Check environment setup

5. Recommended Delivery Loop

1. **Model the stack**

• Start with L2 constructs and extract repeated logic into custom constructs.

2. **Run `cdk synth`**

• Checkpoint: synthesis succeeds with no missing imports, invalid props, missing context, or unresolved references.
• If it fails: fix the construct configuration or context values, then rerun `cdk synth`.

3. **Run infrastructure tests**

• Checkpoint: assertions cover IAM scope, stateful resources, and critical outputs.
• If tests fail: update the stack or test expectations, then rerun the test suite.

4. **Run `cdk diff`**

• Checkpoint: review IAM broadening, resource replacement, export changes, and deletes on stateful resources.
• If the diff is risky: adjust names, dependencies, or `RemovalPolicy`, then rerun `cdk diff`.

5. **Run `cdk deploy`**

• Checkpoint: the stack reaches `CREATE_COMPLETE` or `UPDATE_COMPLETE`.
• If deploy fails: inspect CloudFormation events, fix quotas, permissions, export conflicts, or bootstrap issues, then retry `cdk deploy`.

6. **Verify runtime outcomes**

• Confirm stack outputs, endpoints, alarms, and integrations behave as expected before moving on.

6. Cross-Stack References

// Stack A exports a value
class NetworkStack extends Stack {
  public readonly vpc: ec2.Vpc;
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.vpc = new ec2.Vpc(this, 'Vpc', { maxAzs: 2 });
  }
}

// Stack B imports it via props
interface AppStackProps extends StackProps {
  vpc: ec2.Vpc;
}
class AppStack extends Stack {
  constructor(scope: Construct, id: string, props: AppStackProps) {
    super(scope, id, props);
    new lambda.Function(this, 'Fn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      vpc: props.vpc,
    });
  }
}

// Wire them together
const network = new NetworkStack(app, 'Network');
new AppStack(app, 'App', { vpc: network.vpc });

Examples

Example 1: Serverless API

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigateway from 'aws-cdk-lib/aws-a