aws-cdk

aws-cdk-lib is the single npm package that comprises the AWS Cloud Development Kit (CDK) v2’s construct library — every AWS service, from S3 and Lambda to EKS and Bedrock, modeled as an object-oriented construct you instantiate in code rather than hand-write as CloudFormation JSON/YAML. It’s maintained by AWS itself, with 300+ service modules, near-daily releases, and jsii-based bindings that let a single TypeScript codebase ship native APIs for Python, Java, C#, and Go.

Constructs come in three abstraction tiers: low-level Cfn* resources that map 1:1 to CloudFormation, curated L2 constructs with sane defaults and IAM/networking wiring, and opinionated L3 patterns for common architectures. Combined with the assertions module for template-level testing, pluggable stack synthesizers for deployment strategies, and an aspects system for cross-cutting policy, aws-cdk-lib underpins most real-world CDK apps deployed via the cdk CLI.

What You Get

• Constructs for 300+ AWS services (EC2, S3, Lambda, ECS, RDS, DynamoDB, EventBridge, and more) at three abstraction levels (L1/L2/L3)
• A CDK core (App, Stack, Stage) for organizing deployable units and multi-environment/multi-account pipelines
• An assertions submodule for writing template-level unit tests against synthesized CloudFormation without deploying
• Aspects, tokens, and custom resource providers for cross-cutting policy enforcement and late-bound value resolution
• Multiple pluggable stack synthesizers controlling how assets and CloudFormation bootstrap resources are referenced at deploy time

Common Use Cases

• Provisioning a full application’s cloud footprint — VPCs, ECS services, RDS databases, and IAM roles as one composable CDK app instead of hand-written CloudFormation YAML
• Building reusable internal infrastructure patterns — an L3 construct wrapping an org’s standard architecture (ALB + Fargate + autoscaling) so product teams consume one construct instead of copying templates
• Testing infrastructure changes without deploying — assertions-module unit tests against synthesized templates in CI catch misconfigured resources before a CloudFormation deploy runs
• Migrating from CDK v1 or raw CloudFormation — consolidating dozens of per-service v1 packages into the single aws-cdk-lib v2 dependency, or wrapping existing templates via CfnInclude while incrementally adopting constructs

Under The Hood

Architecture Execution starts in core/lib/app.ts, where an App (a Stage subclass) holds a tree of Construct nodes built on the external constructs library; each Stack (core/lib/stack.ts, ~2000 lines) collects CfnResource/CfnElement nodes that map constructs onto CloudFormation entities. Values that can’t be known until deploy time flow through a Token/Lazy resolution system evaluated during synthesis, while cross-stack references are tracked explicitly (cross-stack-reference-strength.ts) so exports/imports and dependency ordering stay correct. Assets (Docker images, file bundles) are staged via asset-staging.ts and handed to a pluggable IStackSynthesizer (default, legacy, CLI-credentials) that decides how bootstrap S3/ECR resources are referenced in the final template — a clean separation between “what to deploy” and “how packaging/bootstrapping works” that lets teams swap deployment strategies without touching construct code.

Tech Stack The library is authored entirely in TypeScript and compiled through jsii, which generates idiomatic Java, Python, C#, and Go bindings from the same source rather than maintaining hand-ported SDKs per language (declared via jsii.targets in package.json for Amazon.CDK.Lib, software.amazon.awscdk, etc.). Core dependencies stay deliberately minimal — @aws-cdk/cloud-assembly-schema and @aws-cdk/cloud-assembly-api for the synthesized output contract, constructs as the sole peer dependency, plus fs-extra, yaml, semver, and jsonschema for internal bookkeeping. The whole repo is an Nx/Lerna-orchestrated monorepo with a custom cdk-build/cdk-package toolchain that builds, lints, and simultaneously publishes to npm, PyPI, Maven Central, NuGet, and Go modules on every release.

Code Quality The aws-cdk-lib package alone carries an extensive Jest-based test suite (jest ^29.7 with jest-each) spanning every service module and the shared core, exercised through a dedicated assertions submodule purpose-built for infrastructure-as-code testing (Template.fromStack, Match matchers) rather than generic mocking. CI runs both AWS CodeBuild PR pipelines and a wide array of GitHub Actions workflows (CodeQL scanning, Codecov collection, integration-test deployment/approval gates), and contribution is governed by explicit design documents (DESIGN_GUIDELINES.md, NEW_CONSTRUCTS_GUIDE.md, mixin/facade guidelines) that enforce naming and API conventions across hundreds of contributors.

API Design The standout developer-experience choice is jsii itself: one TypeScript codebase yields native-feeling APIs in five languages without hand-maintained per-language ports, which is uncommon among infrastructure tooling. Layering L1 (raw CloudFormation), L2 (ergonomic defaults), and L3 (opinionated patterns) constructs gives an escape hatch from convenience to full control without switching tools, and the token/Lazy system removes the usual friction of not knowing values (ARNs, generated names) until deploy time — code stays declarative even when values are late-bound.