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

Model the stack

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

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 .

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.

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 .

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 .

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

• One concern per stack — Separate network, compute, storage, and monitoring.

• Prefer L2 constructs — Drop to Cfn* only when you need unsupported properties.

• Set explicit environments — Pass env with account and region; avoid implicit production targets.

• Use grant helpers — Prefer .grant*() over handwritten IAM where possible.

• Review the diff before deploy — Treat IAM expansion, replacement, and deletes as mandatory checkpoints.

• Test infrastructure — Cover critical resources with fine-grained assertions.

• Avoid hardcoded values — Use context, parameters, or environment variables.

• 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