Repository Structure

Relevant source files

The following files were used as context for generating this wiki page:

• lerna.json
• package.json
• README.md
• pack.sh
• packages/aws-cdk/package.json
• packages/@aws-cdk/aws-s3-assets/package.json
• packages/@aws-cdk/example-construct-library/README.md
• packages/@aws-cdk/cfnspec/build-tools/build.ts
• packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts
• design/construct-tree.md
• tools/cdk-release/lib/index.ts
• scripts/jetbrains-remove-node-modules.js
• packages/decdk/examples/pipeline.json
• packages/awslint/package.json
• tools/prlint/lint.ts
• packages/@aws-cdk/cloudformation-include/build.js

The AWS CDK repository is a monorepo that contains the source code for the AWS Cloud Development Kit, a framework for defining cloud infrastructure in code. The repository is managed using Lerna and Yarn Workspaces to handle its numerous packages, which include the CDK command-line interface (CLI), the AWS Construct Library modules, and various build and development tools. This structure facilitates coordinated development, testing, and release of all components.

The project is built to support multiple programming languages (TypeScript, Python, Java, .NET, Go) through the jsii toolchain, which allows code written in TypeScript to be transpiled and packaged for use in other languages. The repository contains extensive tooling for building, packaging, and testing these multi-language libraries.

Sources: README.md, package.json, lerna.json

Monorepo Management

The repository uses a combination of Yarn Workspaces and Lerna to manage its multi-package structure.

• Yarn Workspaces: Manages dependencies across the entire project. It hoists common dependencies to the root node_modules directory to reduce duplication and ensures that local packages can reference each other via symlinks. The workspace configuration is defined in the root package.json.
• Lerna: Used for orchestrating commands across the multiple packages. It leverages the Yarn Workspaces structure to run scripts like build, test, and pkglint in the correct topological order.

Sources: package.json:73-86, lerna.json

Workspace Configuration

The workspaces key in the root package.json defines the locations of the individual packages that form the monorepo.

// package.json:73-86
"workspaces": {
  "packages": [
    "packages/*",
    "packages/@aws-cdk/*",
    "packages/@aws-cdk-containers/*",
    "packages/@monocdk-experiment/*",
    "packages/@aws-cdk/*/lambda-packages/*",
    "tools/*",
    "scripts/script-tests"
  ],
  "nohoist": [
    "**/jszip",
    "**/jszip/**",
    // ... many other entries
  ]
}

The nohoist section is critical for preventing certain dependencies from being hoisted to the root, which is often necessary for packages that have specific dependency requirements or are bundled differently.

Sources: package.json:73-157

High-Level Directory Structure

The repository is organized into several key top-level directories that separate concerns between application code, tooling, and documentation.

Directory	Description
packages/	Contains all publishable packages, including the core framework, AWS construct libraries (@aws-cdk/*), and the aws-cdk CLI.
tools/	Contains internal development and build tools, such as cdk-build-tools, cdk-release, and prlint. These are also managed as packages within the workspace.
scripts/	Holds various utility and maintenance scripts, such as jetbrains-remove-node-modules.js for IDE configuration.
design/	Contains design documents and RFCs, like construct-tree.md, which outlines proposals for new features.

Sources: package.json:75-81, design/construct-tree.md, scripts/jetbrains-remove-node-modules.js, tools/prlint/lint.ts

This diagram shows the high-level organization of the monorepo.

Individual Package Structure

Most packages within the packages/ directory, especially the AWS construct libraries, follow a standardized structure. The packages/@aws-cdk/example-construct-library serves as a template for creating new construct libraries.

A typical construct library package contains the following:

File / Directory	Purpose
lib/	Contains the TypeScript source code for the constructs.
test/	Contains unit and integration tests for the constructs.
package.json	Defines package metadata, dependencies, build scripts, and jsii configuration for multi-language support.
.npmignore	Specifies files to exclude from the final npm package.
README.md	Documentation for the package, often including stability banners.
jest.config.js	Jest test runner configuration, usually inheriting from a base config in cdk-build-tools.
.eslintrc.js	ESLint configuration, also inheriting from a base config.

Sources: packages/@aws-cdk/example-construct-library/README.md

package.json Configuration

The package.json file is central to defining how a package is built, tested, and published.

Key sections include:

• jsii: Configures jsii-pacmak to generate language-specific bindings (Java, .NET, Python).
• scripts: Defines standard build commands like build, watch, test, and package, which are typically wrappers around cdk-build-tools commands.
• cdk-build: A custom section that provides metadata for the cdk-build-tools, such as the CloudFormation namespace (cloudformation: "AWS::S3") and Jest configuration.
• stability / maturity: Indicates the stability level of the package (e.g., stable, experimental).

Below is an example from the @aws-cdk/aws-s3-assets package.

// packages/@aws-cdk/aws-s3-assets/package.json:5-30
"jsii": {
  "outdir": "dist",
  "targets": {
    "java": {
      "package": "software.amazon.awscdk.services.s3.assets",
      "maven": {
        "groupId": "software.amazon.awscdk",
        "artifactId": "s3-assets"
      }
    },
    "dotnet": {
      "namespace": "Amazon.CDK.AWS.S3.Assets",
      "packageId": "Amazon.CDK.AWS.S3.Assets",
      "iconUrl": "https://raw.githubusercontent.com/aws/aws-cdk/master/logo/default-256-dark.png"
    },
    "python": {
      "distName": "aws-cdk.aws-s3-assets",
      "module": "aws_cdk.aws_s3_assets",
      "classifiers": [
        "Framework :: AWS CDK",
        "Framework :: AWS CDK :: 1"
      ]
    }
  },
  "projectReferences": true
},

Sources: packages/@aws-cdk/aws-s3-assets/package.json:5-30, packages/@aws-cdk/aws-ecr/package.json:5-30

Build and Packaging Process

The build and packaging process is orchestrated by a series of scripts and tools, culminating in the creation of distributable artifacts for multiple languages.

Build Orchestration

The root pack.sh script is the entry point for packaging all modules. It performs the following high-level steps:

1. Separates packages into jsii and non-jsii groups.
2. Uses jsii-rosetta to extract code samples for documentation.
3. Invokes jsii-pacmak to compile TypeScript and generate packages for all target languages (.jar for Java, nupkg for .NET, sdist/wheel for Python).
4. Runs the package script for non-jsii modules.
5. Merges all generated artifacts from individual package dist directories into a single root dist directory.
6. Generates a build.json file with version and commit information.

Sources: pack.sh

The following diagram illustrates this packaging flow.

CloudFormation Spec Processing

Many AWS construct libraries are generated from the AWS CloudFormation specification. The @aws-cdk/cfnspec package contains tooling for this process.

1. Specification Aggregation: The packages/@aws-cdk/cfnspec/build-tools/build.ts script reads all source specification fragments (spec-source/*.json) and merges them into a single spec/specification.json file. It also applies patch files during this process.
2. L1 Construct Generation: The cfn2ts tool (invoked via cdk-build) uses this unified specification to generate L1 (Layer 1) constructs, which are direct mappings to CloudFormation resources.
3. Automatic Module Creation: The create-missing-libraries.ts script automatically scaffolds new construct library packages for CloudFormation namespaces that don't yet have one, ensuring comprehensive coverage. It generates package.json, lib/index.ts, and other boilerplate files.

Sources: packages/@aws-cdk/cfnspec/build-tools/build.ts, packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts, packages/@aws-cdk/aws-ecr/package.json:62-68

This diagram shows the flow from CloudFormation spec to a generated CDK package.

Synthesis-Time Artifacts

The CDK is designed to produce artifacts during the cdk synth command. Beyond CloudFormation templates, it can also generate a representation of the application's construct hierarchy.

Construct Tree

As proposed in design/construct-tree.md, the CDK can generate a tree.json file in the cdk.out directory. This file represents the entire construct tree of the application, including constructs, their children, and metadata.

The purpose of this artifact is to enable better tooling and debugging experiences by providing a structured view of the application's components, their properties, and their relationships, without needing to parse CloudFormation templates.

The tree.json has a root tree object with a recursive children structure. Each node has a path and an optional attributes bag for metadata.

// design/construct-tree.md:143-178
{
  "version": "tree-0.1",
  "tree": {
    "id": "App",
    "path": "",
    "children": {
      "mystack": {
        "path": "mystack",
        "children": {
          "mytopic": {
            "path": "mystack/mytopic",
            "attributes": {
              "aws:cdk:cloudformation:type": "AWS::SNS::Topic",
              "aws:cdk:cloudformation:properties": {
                "DisplayName": "MyTopic"
              }
            }
          }
        }
      }
    }
  }
}

Sources: design/construct-tree.md:143-178