Mastering AWS CDK v2 (TypeScript)

Focused guidance for building, deploying, and troubleshooting AWS CDK v2 infrastructure in TypeScript.

Contents

• [Use This Skill When](#use-this-skill-when)
• [Trigger Terms](#trigger-terms)
• [Quick Start](#quick-start)
• [Workflow](#workflow)
• [Reference Map](#reference-map)
• [Guardrails](#guardrails)
• [Debugging Checklist](#debugging-checklist)
• [When Not to Use](#when-not-to-use)
• [Reference Files](#reference-files)

Use This Skill When

• Building new CDK apps or stacks in TypeScript
• Refactoring or splitting stacks to manage limits
• Debugging synth/diff/deploy failures or CloudFormation rollbacks
• Importing existing resources into CDK management
• Driving stacks from JSON/YAML configuration files
• Setting up GitHub Actions OIDC deployments
• Implementing service patterns across AWS managed services
• Writing CDK tests and running security checks

Trigger Terms

Use for queries mentioning: cdk, cdk deploy, cdk diff, cdk synth, cdk import, cdk watch, cdk refactor, cdk bootstrap, cdk-nag, hotswap, CloudFormation, stack rollback, cdk.context.json, cdk.json, SSM Parameter Store, hnb659fds, or OIDC GitHub Actions.

Quick Start

1. Confirm target account, region, and environment (dev/stage/prod).
2. Run cdk synth then cdk diff to validate changes.
3. Deploy with cdk deploy --require-approval=never in CI.

Workflow

1) Intake

Collect:

• account and region
• environment name and stage
• target services and integrations
• existing resources to import or avoid replacement

2) Stack Design

• Keep stacks under 500 resources (split or use nested stacks)
• Pass outputs via props or explicit exports
• Set removal policies for stateful resources (retain by default)

3) Implement

• Prefer L2 constructs; use L1 only for gaps
• Apply least-privilege IAM grants
• Keep resource names deterministic

4) Validate

• cdk synth to inspect the template
• cdk diff to review changes
• cdk doctor for environment issues

5) Deploy

• Ensure bootstrap completed for the account/region
• Review CloudFormation events on failure
• Use --require-approval=never only for CI

6) Observability

• Add log retention, alarms, and dashboards early
• Use X-Ray where distributed tracing matters
• See [observability.md](references/observability.md)

Reference Map

Guardrails

• Do not modify CloudFormation-managed resources in the console
• Avoid dynamic values (Date.now, random) in resource definitions
• Use env: { account, region } for lookups (VPC/AZ/AMI)
• Use stable IDs when generating constructs from config data
• Use cdk import (adopt) for existing resources; use fromXxx only for read-only references
• Do not use hotswap in production pipelines

Debugging Checklist

Copy and track progress:

Debugging Progress:
- [ ] Check CloudFormation events (Console -> Stack -> Events)
- [ ] Re-run with verbose output: `cdk deploy --progress events`
- [ ] Inspect template: `cdk synth > template.yaml`
- [ ] Run diff: `cdk diff`
- [ ] Check service logs (Lambda: CloudWatch, ECS: task events)
- [ ] Run `cdk doctor`

When Not to Use

• Terraform/Pulumi or raw CloudFormation templates
• Manual console-driven resource management
• CDK in Python/Java/Go/C# (TypeScript only)

Reference Files

• [references/troubleshooting.md](references/troubleshooting.md) -- Error messages and fixes
• [references/cicd-github.md](references/cicd-github.md) -- GitHub Actions OIDC setup
• [references/services.md](references/services.md) -- Lambda, ECS, MSK, DynamoDB, Aurora, S3, EventBridge patterns
• [references/observability.md](references/observability.md) -- CloudWatch, X-Ray, dashboards, alarms
• [references/architecture-ops.md](references/architecture-ops.md) -- Determinism, configuration-driven patterns, imports, drift, and operational workflows
• [references/testing-security.md](references/testing-security.md) -- CDK testing, cdk-nag, and compliance checks
• [references/latest-features.md](references/latest-features.md) -- New constructs, CLI capabilities, and recent patterns