giuseppe-trisciuoglio/aws-cdk

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-apigateway';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

class ServerlessApiStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, 'Items', {
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    const fn = new lambda.Function(this, 'Handler', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: { TABLE_NAME: table.tableName },
    });

    table.grantReadWriteData(fn);

    new apigateway.LambdaRestApi(this, 'Api', { handler: fn });
  }
}

Example 2: CDK Assertion Test

import { Template } from 'aws-cdk-lib/assertions';
import { App } from 'aws-cdk-lib';
import { ServerlessApiStack } from '../lib/serverless-api-stack';

test('creates DynamoDB table with PAY_PER_REQUEST', () => {
  const app = new App();
  const stack = new ServerlessApiStack(app, 'TestStack');
  const template = Template.fromStack(stack);

  template.hasResourceProperties('AWS::DynamoDB::Table', {
    BillingMode: 'PAY_PER_REQUEST',
  });

  template.resourceCountIs('AWS::Lambda::Function', 1);
});

Best Practices

1. One concern per stack — Separate network, compute, storage, and monitoring.
2. Prefer L2 constructs — Drop to Cfn* only when you need unsupported properties.
3. Set explicit environments — Pass env with account and region; avoid implicit production targets.
4. Use grant helpers — Prefer .grant*() over handwritten IAM where possible.
5. Review the diff before deploy — Treat IAM expansion, replacement, and deletes as mandatory checkpoints.
6. Test infrastructure — Cover critical resources with fine-grained assertions.
7. Avoid hardcoded values — Use context, parameters, or environment variables.
8. Use the right RemovalPolicy — RETAIN for production data, DESTROY only for disposable environments.

Constraints and Warnings

• CloudFormation limits — Max 500 resources per stack; split large apps into multiple stacks
• Synthesis is not deployment — cdk synth only generates templates; cdk deploy applies changes
• Cross-stack references create CloudFormation exports; removing them requires careful ordering
• Stateful resources (RDS, DynamoDB, S3 with data) — Always set removalPolicy: RETAIN in production
• Bootstrap required — Run cdk bootstrap once per account/region before first deploy
• Asset bundling — Lambda code and Docker images are uploaded to the CDK bootstrap bucket

References

Detailed implementation guides are available in the references/ directory:

• Core Concepts — App lifecycle, stacks, constructs, environments, assets
• Serverless Patterns — Lambda, API Gateway, DynamoDB, S3 events, Step Functions
• Networking & VPC — VPC design, subnets, NAT, security groups, VPC endpoints
• Security Hardening — IAM, KMS, Secrets Manager, WAF, compliance
• Testing Strategies — Assertions, snapshots, integration tests, CDK Nag