Core Concepts: App, Stack, and Construct
Relevant source files
The following files were used as context for generating this wiki page:
The AWS Cloud Development Kit (AWS CDK) uses a hierarchical structure composed of three core concepts: Constructs, Stacks, and Apps. These components work together to allow developers to define cloud infrastructure in code using modern programming languages. Constructs are the basic building blocks, which are composed into Stacks, the units of deployment. An App is the root container for one or more Stacks, representing a complete application.
Understanding this hierarchy is fundamental to using the CDK effectively. Developers define reusable cloud components as Constructs, assemble them into Stacks that map to AWS CloudFormation templates, and manage the entire application lifecycle through an App object. This model provides a powerful, object-oriented abstraction for defining and provisioning AWS resources.
Sources: README.md:20-24, packages/@aws-cdk/core/README.md:12-20
The Construct Tree Hierarchy
All CDK applications are composed as a tree of constructs, known as the construct tree. The App is the root of this tree. Stacks are children of the App, and resources (which are also constructs) are children of Stacks. This hierarchy defines the scope and lifecycle of all components within a CDK application.
The following diagram illustrates the typical hierarchy of a CDK application.
This diagram shows an App containing two Stacks. One Stack contains a higher-level Construct which in turn is composed of several AWS resources.
Sources: design/construct-tree.md:10-13, packages/@aws-cdk/core/README.md:22-31
Constructs: The Building Blocks
Constructs are the fundamental building blocks of any AWS CDK application. A construct can represent a single, low-level AWS resource (like an S3 bucket) or a higher-level, abstract component consisting of multiple AWS resources (like a VPC with all its subnets and gateways).
There are different levels of constructs:
- L1 (Layer 1) Constructs: These are low-level constructs that map directly to AWS CloudFormation resources. They are auto-generated from the CloudFormation specification.
- L2 (Layer 2) Constructs: These are higher-level, intent-based constructs that provide convenient defaults and boilerplate reduction. They are the primary interface for most CDK development.
- L3 (Layer 3) Constructs: These are even higher-level patterns, often encapsulating an entire application or a complex multi-resource architecture.
Sources: design/construct-tree.md:15-19, packages/@aws-cdk/example-construct-library/README.md:14-17
The tree.json Artifact
During synthesis (cdk synth), the CDK can generate an artifact called tree.json which represents the construct tree of the application. This file is intended to enrich the developer experience by providing a machine-readable view of the application's structure, properties, and relationships. It is useful for debugging, building custom tooling, and gaining insight into what the CDK generates on your behalf.
The tree.json file is produced at synthesis time and does not require connectivity to AWS.
Sources: design/construct-tree.md:60-63, design/construct-tree.md:83-86
The structure of the tree.json file contains a nested map of constructs, each with properties describing its place in the tree.
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Required | The construct's ID within its scope. |
path | string | Required | The full, absolute path of the construct within the tree. |
children | object | Not Required | A map of direct children of this construct. |
attributes | object | Not Required | A key-value map of arbitrary metadata associated with the construct. |
Sources: design/construct-tree.md:92-100, design/construct-tree.md:109-113
An example snippet of tree.json:
{
"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:119-148
Stacks: Units of Deployment
A Stack is the smallest physical unit of deployment in the CDK and maps directly to an AWS CloudFormation Stack. You define a stack by creating a class that extends Stack and instantiating constructs within its constructor.
Key characteristics of a Stack:
- It contains a collection of constructs that define AWS resources.
- It is instantiated within an
App. - It is scoped to a specific AWS account and region.
- Resources within different stacks can reference each other, and the CDK will automatically create CloudFormation Exports and
Fn::ImportValueintrinsics to manage these dependencies.
Sources: packages/@aws-cdk/core/README.md:12-15, packages/@aws-cdk/core/README.md:65-72
Nested Stacks
For complex applications, you can use NestedStack to create stacks as part of other stacks. This helps manage complexity and reuse common components. The CDK automatically wires resource references across parent and nested stack boundaries using CloudFormation parameters and outputs.
class MyNestedStack extends cfn.NestedStack {
constructor(scope: Construct, id: string, props?: cfn.NestedStackProps) {
super(scope, id, props);
new s3.Bucket(this, 'NestedBucket');
}
}
class MyParentStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new MyNestedStack(this, 'Nested1');
}
}
Sources: packages/@aws-cdk/core/README.md:46-63
App: The Application Root
The App class is the root of the construct tree. Its primary purpose is to act as a container for all the stacks that define your application. When you run cdk synth, the CDK Toolkit executes your app file, which instantiates the App object and all the stacks and constructs within it. The result is a cloud assembly (cdk.out directory) containing one or more CloudFormation templates.
An App is defined at the beginning of a CDK application's entry point file.
// Example from a CDK app entrypoint
const app = new cdk.App();
new MyFirstStack(app, 'MyFirstStack');
new MySecondStack(app, 'MySecondStack');
Sources: README.md:22-23, packages/aws-cdk/lib/init-templates/v2/app/javascript/README.md:5-6
Synthesis Flow
The cdk synth command triggers the synthesis process, which converts the construct tree into a cloud assembly.
This diagram shows the process from running cdk synth to generating the final CloudFormation templates in the cdk.out directory.
Sources: README.md:73-74, design/construct-tree.md:83-84
Core Class Relationships
The App, Stack, and other constructs inherit from a common base class, forming a clear inheritance hierarchy.
This diagram shows that App, Stack, and CfnResource are all specialized types of Construct.
Sources: packages/@aws-cdk/core/README.md:12-15, packages/@aws-cdk/core/README.md:29-31
Comparison of Core Concepts
| Concept | Role | Maps To CloudFormation | Scope |
|---|---|---|---|
| App | Root container for the application | N/A | An entire CDK application |
| Stack | Unit of deployment | AWS::CloudFormation::Stack | An AWS account and region |
| Construct | Reusable building block | One or more resources | Defined by its parent in the tree |
Sources: README.md:20-24, packages/@aws-cdk/core/README.md:12-15, design/construct-tree.md:15-19
Summary
The App, Stack, and Construct are the three pillars of the AWS CDK's programming model. Constructs provide a way to define AWS resources with the power of a programming language. Stacks group these constructs into deployable units that correspond to CloudFormation stacks. Finally, the App serves as the root of the entire application, containing all stacks and orchestrating the synthesis process. This hierarchical and compositional model is what gives the CDK its power and flexibility, enabling developers to build complex, reusable, and maintainable cloud infrastructure as code.
Sources: README.md:11-16, packages/@aws-cdk/core/README.md:8-11