AWS CDK Deep Dive

May 23, 2026 18 min read DevOps

awscdkinfrastructure-as-codedevopstypescriptcloudplatform-engineering

AWS CDK is an infrastructure-as-code framework that lets you define AWS resources using TypeScript, Python, Go, Java, or C#. The synthesized output is CloudFormation—CDK is a CloudFormation generator, not a replacement—but the authoring experience is fundamentally different. Instead of writing hundreds of lines of YAML, you instantiate constructs in code, use loops and conditions natively, extract shared patterns into reusable components, and write tests against the synthesized output.

Whether CDK is the right choice depends heavily on your team, your existing tooling, and what you are building. This post works through the full CDK programming model, from the three construct levels through CDK Pipelines and testing, and ends with a direct comparison against Terraform that does not pull punches.

The Construct Tree

Every CDK application is a tree of constructs. At the root is the App. Below the App are one or more Stack objects. Below each Stack are the constructs that represent AWS resources. The tree structure determines resource IDs (used for CloudFormation logical IDs), the scope for grants and permissions, and how outputs and cross-references resolve.

App
├── NetworkStack (Stack)
│   ├── VPC (ec2.Vpc)
│   │   ├── PublicSubnet1 (ec2.PublicSubnet)
│   │   └── PublicSubnet2 (ec2.PublicSubnet)
│   └── SecurityGroup (ec2.SecurityGroup)
└── AppStack (Stack)
    ├── WebhookHandler (Custom Construct)
    │   ├── Bucket (s3.Bucket)
    │   └── Function (lambda.Function)
    └── Api (apigateway.RestApi)

Each node in the tree has an id (local within its parent) and a path (the full path from root). The path is used to generate stable CloudFormation logical IDs. If you rename or move a construct, the logical ID changes, and CloudFormation treats it as delete-and-recreate. This is the primary footgun for CDK refactoring.

Construct Levels

CDK constructs come in three levels of abstraction. Understanding which to use and when is the foundation of working effectively with CDK.

L1: CloudFormation Wrappers

L1 constructs map one-to-one to CloudFormation resource types. They are prefixed with Cfn (for CloudFormation). CfnBucket, CfnFunction, CfnTable. L1 constructs expose every CloudFormation property but provide no defaults or higher-level semantics.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


import { aws_s3 as s3 } from 'aws-cdk-lib';

new s3.CfnBucket(this, 'RawBucket', {
  bucketName: 'my-raw-bucket',
  versioningConfiguration: {
    status: 'Enabled',
  },
  corsConfiguration: {
    corsRules: [{
      allowedHeaders: ['*'],
      allowedMethods: ['GET'],
      allowedOrigins: ['https://example.com'],
      maxAge: 3600,
    }],
  },
});

You rarely write L1 constructs directly. Their main use is as an escape hatch when an L2 construct does not yet expose a CloudFormation property you need.

L2: Curated Constructs

L2 constructs are the everyday CDK interface. They wrap one CloudFormation resource with an opinionated, intent-based API that embeds AWS best practices as defaults.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import { aws_s3 as s3, aws_lambda as lambda, RemovalPolicy } from 'aws-cdk-lib';

const bucket = new s3.Bucket(this, 'AssetBucket', {
  encryption: s3.BucketEncryption.S3_MANAGED,
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
  versioned: true,
  removalPolicy: RemovalPolicy.RETAIN,  // Don't delete on stack destroy
  autoDeleteObjects: false,
});

const fn = new lambda.Function(this, 'Processor', {
  runtime: lambda.Runtime.NODEJS_20_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset('src/processor'),
  memorySize: 512,
  timeout: Duration.seconds(30),
  environment: {
    BUCKET_NAME: bucket.bucketName,
  },
});

// Grant creates the IAM policy automatically
bucket.grantRead(fn);

The grantRead call does more than add an IAM statement—it creates a well-scoped policy with the correct S3 actions (s3:GetObject, s3:ListBucket) on the specific bucket ARN, and attaches it to the Lambda execution role. This is representative of L2’s value: the permission grant is one line, correct by construction, and requires no IAM knowledge from the caller.

L2 constructs also expose strongly typed references. bucket.bucketName returns a CDK token that resolves at synthesis time to the actual bucket name. Pass it between constructs without hardcoding names or using SSM lookups.

L3: Patterns

L3 constructs (also called pattern constructs) combine multiple L2 resources into a working architectural pattern. apigateway.LambdaRestApi creates an API Gateway REST API wired to a Lambda function in three lines; ecs_patterns.ApplicationLoadBalancedFargateService creates an ALB, ECS cluster, Fargate task definition, and all supporting IAM roles in one construct.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import { aws_apigateway as apigw, aws_lambda as lambda } from 'aws-cdk-lib';

const handler = new lambda.Function(this, 'Handler', {
  runtime: lambda.Runtime.PYTHON_3_12,
  handler: 'app.handler',
  code: lambda.Code.fromAsset('src'),
});

// Creates REST API + Lambda integration + deployment stage + usage plan
const api = new apigw.LambdaRestApi(this, 'Api', {
  handler,
  proxy: false,  // Disable catch-all proxy; define routes explicitly
  deployOptions: {
    stageName: 'v1',
    throttlingBurstLimit: 1000,
    throttlingRateLimit: 500,
  },
});

const items = api.root.addResource('items');
items.addMethod('GET');
items.addMethod('POST');

L3 constructs are excellent for getting started quickly. Their limitation is inflexibility—if the pattern does not match your exact needs, you may find yourself fighting the abstraction. In that case, compose L2 constructs directly.

Stacks and Environments

A Stack is a CDK construct that represents a single CloudFormation stack. Each Stack synthesizes to one CloudFormation template. Stacks are the unit of deployment—you deploy, update, and destroy stacks independently.

Environment Pinning

An environment in CDK terms is an account and region pair. Stacks can be environment-specific or environment-agnostic.

Environment-specific stacks know their target account and region:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


const app = new App();

new AppStack(app, 'AppDev', {
  env: { account: '111111111111', region: 'us-east-1' },
  config: devConfig,
});

new AppStack(app, 'AppProd', {
  env: { account: '999999999999', region: 'us-east-1' },
  config: prodConfig,
});

Knowing the environment enables context lookups at synthesis time—VPC IDs, availability zones, SSM parameters. L2 constructs like ec2.Vpc.fromLookup require a known environment.

Environment-agnostic stacks omit the env property. They can deploy to any account/region but cannot use context lookups. Useful for generic constructs published as libraries, or for stacks whose target environment is resolved at deployment time:

1

cdk deploy AppStack --profile my-dev-profile

Cross-Stack References

When one stack needs a value from another (a VPC ID, a bucket name, a Lambda ARN), you have two options.

CloudFormation exports (CfnOutput with exportName) create a hard dependency between stacks. If the producing stack changes or deletes the export, CloudFormation blocks the operation until the consuming stack is updated. In practice, this creates deployment ordering problems and makes stacks brittle.

SSM Parameter Store is the better pattern for cross-stack sharing:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


// NetworkStack: store outputs in SSM
class NetworkStack extends Stack {
  constructor(scope: App, id: string, props: StackProps) {
    super(scope, id, props);

    const vpc = new ec2.Vpc(this, 'VPC', {
      maxAzs: 3,
      natGateways: 1,
    });

    new ssm.StringParameter(this, 'VpcId', {
      parameterName: '/platform/vpc-id',
      stringValue: vpc.vpcId,
    });

    new ssm.StringListParameter(this, 'PrivateSubnets', {
      parameterName: '/platform/private-subnet-ids',
      stringListValue: vpc.privateSubnets.map(s => s.subnetId),
    });
  }
}

// AppStack: read from SSM
class AppStack extends Stack {
  constructor(scope: App, id: string, props: StackProps) {
    super(scope, id, props);

    // Synthesis-time lookup (requires known environment, makes a live AWS call)
    const vpcId = ssm.StringParameter.valueFromLookup(this, '/platform/vpc-id');

    const vpc = ec2.Vpc.fromLookup(this, 'VPC', { vpcId });

    new ecs.Cluster(this, 'Cluster', { vpc });
  }
}

SSM lookups during synthesis make a live AWS API call. The result is cached in cdk.context.json—commit this file so CI builds are deterministic and don’t require AWS credentials to synthesize.

Custom Constructs

Custom constructs are how CDK pays off at scale. Rather than repeating the same S3 + Lambda + IAM pattern across twenty stacks, you write it once as a construct, publish it as an npm package, and consume it everywhere.

A construct is any TypeScript class that extends Construct:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import { Construct } from 'constructs';
import {
  aws_s3 as s3,
  aws_lambda as lambda,
  aws_lambda_event_sources as sources,
  aws_sqs as sqs,
  Duration, RemovalPolicy
} from 'aws-cdk-lib';

export interface S3EventProcessorProps {
  /** Handler function entry point */
  handler: string;
  /** Path to Lambda code asset directory */
  codePath: string;
  /** Memory for the Lambda function in MB. Default: 512 */
  memoryMB?: number;
  /** Maximum concurrent invocations. Default: 10 */
  maxConcurrency?: number;
}

export class S3EventProcessor extends Construct {
  public readonly bucket: s3.Bucket;
  public readonly function: lambda.Function;
  public readonly dlq: sqs.Queue;

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

    this.dlq = new sqs.Queue(this, 'DLQ', {
      retentionPeriod: Duration.days(14),
    });

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

    this.function = new lambda.Function(this, 'Function', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: props.handler,
      code: lambda.Code.fromAsset(props.codePath),
      memorySize: props.memoryMB ?? 512,
      reservedConcurrentExecutions: props.maxConcurrency ?? 10,
      deadLetterQueue: this.dlq,
      environment: {
        BUCKET_NAME: this.bucket.bucketName,
      },
    });

    this.function.addEventSource(
      new sources.S3EventSource(this.bucket, {
        events: [s3.EventType.OBJECT_CREATED],
      })
    );

    this.bucket.grantRead(this.function);
  }
}

Expose the internal resources (bucket, function, dlq) as public properties so callers can further configure them:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


const processor = new S3EventProcessor(this, 'ImageProcessor', {
  handler: 'index.handler',
  codePath: 'src/image-processor',
  memoryMB: 1024,
});

// Caller adds additional permissions
processor.function.addToRolePolicy(new iam.PolicyStatement({
  actions: ['rekognition:DetectLabels'],
  resources: ['*'],
}));

// Caller subscribes to DLQ for monitoring
const alarm = new cloudwatch.Alarm(this, 'DLQAlarm', {
  metric: processor.dlq.metricNumberOfMessagesVisible(),
  threshold: 1,
  evaluationPeriods: 1,
});

The construct ID (ImageProcessor) namespaces all child construct IDs. The S3 bucket gets logical ID ImageProcessorBucketABC123, the Lambda gets ImageProcessorFunctionXYZ456. This means you can use the same construct class multiple times in the same stack without ID collisions—just give each instance a unique ID.

Escape Hatches

CDK’s L2 constructs do not expose every CloudFormation property. When you need a property that L2 has not surfaced, the escape hatch is the .node.defaultChild accessor, which returns the underlying L1 CfnResource.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


const bucket = new s3.Bucket(this, 'Bucket');

// Get the underlying CfnBucket
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;

// Add a property override (dot-notation for nested properties)
cfnBucket.addPropertyOverride(
  'LifecycleConfiguration.Rules.0.NoncurrentVersionTransitions.0',
  {
    StorageClass: 'STANDARD_IA',
    TransitionInDays: 30,
  }
);

// Override the DeletionPolicy
cfnBucket.addOverride('DeletionPolicy', 'Retain');

// Add metadata (used by cfn-init on EC2 instances)
cfnBucket.cfnOptions.metadata = {
  'aws:cdk:path': 'MyStack/Bucket/Resource',
};

For resources where CDK has no L2 at all, use CfnResource directly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// Resource with no CDK L2 support
new CfnResource(this, 'CustomResource', {
  type: 'AWS::SomeService::SomeResource',
  properties: {
    PropertyA: 'value-a',
    PropertyB: {
      NestedProperty: 'nested-value',
    },
  },
});

Use escape hatches sparingly. They produce correct CloudFormation but bypass CDK’s type checking and grant mechanics. When you find yourself frequently escaping the same L2 construct, the construct probably has a gap worth opening a GitHub issue for.

CDK Pipelines

CDK Pipelines is a construct library for building deployment pipelines that deploy CDK applications. The distinctive feature is self-mutation: the first deployment creates the CodePipeline, and every subsequent commit to the source repo can update the pipeline definition without manual intervention.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


import { Stack, StackProps, SecretValue } from 'aws-cdk-lib';
import { pipelines, aws_codebuild as codebuild } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class PipelineStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
      pipelineName: 'MyAppPipeline',
      crossAccountKeys: true,  // Required for cross-account deployments
      dockerEnabledForSynth: true,  // If synth needs Docker (e.g., bundling)
      synth: new pipelines.ShellStep('Synth', {
        input: pipelines.CodePipelineSource.gitHub('myorg/myapp', 'main', {
          authentication: SecretValue.secretsManager('github-token'),
        }),
        commands: [
          'npm ci',
          'npm run build',
          'npm run test',
          'npx cdk synth',
        ],
        primaryOutputDirectory: 'cdk.out',
      }),
    });

    // Dev stage — deploys immediately
    pipeline.addStage(new AppStage(this, 'Dev', {
      env: { account: '111111111111', region: 'us-east-1' },
    }));

    // Prod stage — requires manual approval
    pipeline.addStage(new AppStage(this, 'Prod', {
      env: { account: '999999999999', region: 'us-east-1' },
    }), {
      pre: [new pipelines.ManualApprovalStep('PromoteToProd')],
      post: [
        new pipelines.ShellStep('SmokeTest', {
          commands: ['curl -f https://api.example.com/health'],
          envFromCfnOutputs: {
            API_URL: appStage.apiUrlOutput,
          },
        }),
      ],
    });
  }
}

class AppStage extends Stage {
  public readonly apiUrlOutput: CfnOutput;

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

    const appStack = new AppStack(this, 'App', props);
    this.apiUrlOutput = appStack.apiUrlOutput;
  }
}

Bootstrap for Cross-Account Deployments

Cross-account deployments require each target account to be bootstrapped with a trust relationship to the pipeline account:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Bootstrap the pipeline account (where CodePipeline runs)
cdk bootstrap aws://PIPELINE_ACCOUNT/us-east-1

# Bootstrap each target account, trusting the pipeline account
cdk bootstrap aws://DEV_ACCOUNT/us-east-1 \
  --trust PIPELINE_ACCOUNT \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

cdk bootstrap aws://PROD_ACCOUNT/us-east-1 \
  --trust PIPELINE_ACCOUNT \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess

The bootstrap creates IAM roles (cdk-QUALIFIER-deploy-role-ACCOUNT-REGION, cdk-QUALIFIER-file-publishing-role-ACCOUNT-REGION) with trust policies allowing the pipeline account’s CodeBuild role to assume them. This is the mechanism by which a CodeBuild job in the pipeline account can deploy to a different account without storing cross-account credentials.

Scope the --cloudformation-execution-policies to the minimum permissions your stacks require. AdministratorAccess is convenient but means a compromised pipeline has full account access.

Testing CDK Applications

The aws-cdk-lib/assertions module provides unit test utilities against the synthesized CloudFormation template. This is CDK’s answer to “how do I know my infrastructure code does what I think?”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


import { App } from 'aws-cdk-lib';
import { Template, Match } from 'aws-cdk-lib/assertions';
import { AppStack } from '../lib/app-stack';

describe('AppStack', () => {
  let template: Template;

  beforeAll(() => {
    const app = new App();
    const stack = new AppStack(app, 'TestStack', {
      environment: 'test',
    });
    template = Template.fromStack(stack);
  });

  test('Lambda function uses Node 20 runtime', () => {
    template.hasResourceProperties('AWS::Lambda::Function', {
      Runtime: 'nodejs20.x',
    });
  });

  test('S3 bucket blocks public access', () => {
    template.hasResourceProperties('AWS::S3::Bucket', {
      PublicAccessBlockConfiguration: {
        BlockPublicAcls: true,
        BlockPublicPolicy: true,
        IgnorePublicAcls: true,
        RestrictPublicBuckets: true,
      },
    });
  });

  test('Lambda has read access to bucket', () => {
    template.hasResourceProperties('AWS::IAM::Policy', {
      PolicyDocument: {
        Statement: Match.arrayWith([
          Match.objectLike({
            Effect: 'Allow',
            Action: Match.arrayWith(['s3:GetObject', 's3:ListBucket']),
          }),
        ]),
      },
    });
  });

  test('Exactly one DynamoDB table', () => {
    template.resourceCountIs('AWS::DynamoDB::Table', 1);
  });

  test('DLQ retention is 14 days', () => {
    template.hasResourceProperties('AWS::SQS::Queue', {
      MessageRetentionPeriod: Match.exact(1209600),  // 14 days in seconds
    });
  });
});

Match.arrayWith asserts that the array contains the specified elements (not that it equals them). Match.objectLike asserts that the object contains the specified properties. Match.exact asserts equality. This gives you fine-grained control over assertion specificity.

Snapshot testing captures the entire synthesized template on first run and compares against it on subsequent runs. It catches unintended changes but produces noisy diffs when legitimate changes occur:

1
2
3
4
5


test('Stack matches snapshot', () => {
  const app = new App();
  const stack = new AppStack(app, 'SnapshotStack', { environment: 'test' });
  expect(Template.fromStack(stack).toJSON()).toMatchSnapshot();
});

Use snapshot tests for constructs that are stable and expensive to reason about manually. Prefer fine-grained assertions for anything you care about specifically—they fail with clear messages and are not broken by unrelated changes.

Integration tests with @aws-cdk/integ-tests-alpha deploy actual stacks to a real AWS account and run assertions against live resources. They are expensive (time and money) but necessary for constructs that depend on runtime behavior:

1
2


# Run integration tests (deploys and destroys real resources)
npx integ-runner --update-on-fail

CDK vs Terraform

This comparison has a clear answer for some teams and is genuinely ambiguous for others.

What CDK Actually Is Under the Hood

CDK synthesizes to CloudFormation. cdk deploy runs cdk synth to generate CloudFormation templates, uploads them to S3, and calls cloudformation:CreateChangeSet followed by cloudformation:ExecuteChangeSet. The deployment speed and behavior is CloudFormation’s—CDK adds synthesis time on top of CloudFormation’s deployment time. A stack that takes 10 minutes to deploy with vanilla CloudFormation takes 10 minutes with CDK.

Drift detection is CloudFormation drift detection—limited to supported resource types, not continuous, requires an explicit detection request. Terraform’s terraform plan detects drift every time you run it, against all resources.

The Honest Table

Concern	CDK	Terraform
Authoring language	TypeScript, Python, Go, Java, C#	HCL (domain-specific)
Loops and conditions	Native (for, if, map)	`for_each`, `count`, ternary
Abstraction and reuse	Constructs as packages on npm/PyPI	Modules on registry.terraform.io
Type safety	Strong (TypeScript) to moderate (Python)	Weak (HCL has types but limited checking)
State management	CloudFormation stacks (AWS-managed)	State files (S3 + DynamoDB locking, or Terraform Cloud)
Drift detection	CloudFormation drift (limited, on-demand)	`terraform plan` (comprehensive, on every apply)
Deployment speed	Slow (CloudFormation intermediary)	Fast (direct AWS API calls)
Multi-cloud	AWS only	AWS, Azure, GCP, everything with a provider
Non-AWS resources	Limited (GitHub, Datadog via custom resources)	Comprehensive (hundreds of providers)
Bootstrap requirement	Yes (CDKToolkit stack)	No
Escape to raw CloudFormation	Easy (escape hatches)	N/A
Testing	Template assertions, snapshot, integ-runner	terratest, terraform-compliance
Mature ecosystem	Growing	Large and mature

When CDK Wins

CDK is the right choice when your team writes TypeScript or Python daily and finds HCL’s lack of abstraction frustrating. If you are building an internal developer platform where teams define their infrastructure as CDK constructs that platform engineers maintain, the ability to publish constructs as npm packages with versioning and type signatures is genuinely valuable. A new PostgresDatabase(this, 'DB', { size: 'small' }) construct that encapsulates RDS Multi-AZ, automated backups, SSM parameter output, and security group rules is impossible to express with equivalent usability in Terraform modules.

CDK also wins when the application code and infrastructure code live together and change together. A Lambda function defined next to its infrastructure code, bundled automatically by CDK’s asset system, deployed with cdk deploy—the feedback loop is tight.

When Terraform Wins

Terraform wins when your infrastructure spans multiple clouds. When you manage Datadog monitors, GitHub repositories, PagerDuty schedules, and Okta groups alongside AWS resources. CDK has no answer for non-AWS resources.

Terraform wins for teams that are not already writing TypeScript or Python at work. HCL has a shallow learning curve; getting productive in CDK requires understanding the programming language, the CDK construct model, CloudFormation concepts, and TypeScript’s type system simultaneously.

Terraform wins when operational simplicity matters more than authoring power. The terraform plan output is universally understood; the CDK synth output is a CloudFormation template that requires CloudFormation knowledge to interpret. When something goes wrong in production, Terraform’s debugging story—read the plan, read the state, look at the resource—is simpler than CDK’s—read the synthesized template, read the CloudFormation events, correlate back to the CDK source.

The Hybrid

Many organizations use both. Terraform for foundational infrastructure: VPCs, EKS clusters, IAM roles, shared databases, DNS. CDK for application infrastructure: Lambda functions, API Gateways, event buses, DynamoDB tables—resources that are closely coupled to application code and change with it. Terraform’s stability and drift detection are valuable for slow-moving shared infrastructure. CDK’s language integration and asset bundling are valuable for fast-moving application infrastructure.

Practical Configuration Patterns

Per-Environment Configuration

Avoid CfnParameter for environment configuration—it makes synthesis non-deterministic and complicates CDK Pipelines. Use typed Stack properties instead:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// config/environments.ts
export interface EnvironmentConfig {
  domainName: string;
  certificateArn: string;
  minCapacity: number;
  maxCapacity: number;
  instanceType: ec2.InstanceType;
  enableXRay: boolean;
}

export const environments: Record<string, EnvironmentConfig> = {
  dev: {
    domainName: 'dev.api.example.com',
    certificateArn: 'arn:aws:acm:us-east-1:111111111:certificate/dev-cert',
    minCapacity: 1,
    maxCapacity: 5,
    instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.SMALL),
    enableXRay: false,
  },
  prod: {
    domainName: 'api.example.com',
    certificateArn: 'arn:aws:acm:us-east-1:999999999:certificate/prod-cert',
    minCapacity: 3,
    maxCapacity: 50,
    instanceType: ec2.InstanceType.of(ec2.InstanceClass.M6G, ec2.InstanceSize.LARGE),
    enableXRay: true,
  },
};

// bin/app.ts
const app = new App();
new AppStack(app, `App-dev`, {
  env: { account: '111111111111', region: 'us-east-1' },
  config: environments.dev,
});
new AppStack(app, `App-prod`, {
  env: { account: '999999999999', region: 'us-east-1' },
  config: environments.prod,
});

Consistent Tagging

Apply tags at the App level to cover all stacks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// bin/app.ts
const app = new App();

Tags.of(app).add('Project', 'MyApp');
Tags.of(app).add('ManagedBy', 'CDK');
Tags.of(app).add('Repository', 'github.com/myorg/myapp');

// Stack-specific tags
const devStack = new AppStack(app, 'App-dev', { config: environments.dev });
Tags.of(devStack).add('Environment', 'development');
Tags.of(devStack).add('CostCenter', 'engineering-dev');

Tags applied to a parent propagate to all children that support tagging. Override at the resource level when a specific resource needs different values.

Asset Bundling

CDK bundles Lambda code automatically. For Node.js, CDK can use esbuild to bundle and minify before uploading:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


const fn = new lambda.NodejsFunction(this, 'Handler', {
  entry: 'src/handlers/api.ts',
  handler: 'handler',
  runtime: lambda.Runtime.NODEJS_20_X,
  bundling: {
    minify: true,
    sourceMap: true,
    externalModules: ['@aws-sdk/*'],  // Exclude SDK (available in runtime)
    nodeModules: ['sharp'],            // Bundle native modules
  },
});

NodejsFunction uses Docker by default for reproducible builds. Pass bundling: { forceDockerBundling: false } to use the local Node.js/esbuild for faster iteration. Use Docker in CI to ensure consistent artifacts.

The --hotswap flag speeds up development iteration by bypassing CloudFormation for code-only changes:

1
2
3
4
5
6


# Hotswap: updates Lambda code and environment variables directly
# Skips CloudFormation for supported change types
cdk deploy --hotswap

# Watch mode: runs hotswap automatically on file changes
cdk watch

Hotswap only works for specific change types (Lambda code, Docker images, environment variables). Any change that requires CloudFormation resources to be created or deleted falls back to a full deployment automatically.