Your First CDK App

Relevant source files

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

• packages/aws-cdk/lib/init.ts
• packages/aws-cdk/lib/init-templates/v2/sample-app/typescript/lib/%name%-stack.template.ts
• packages/aws-cdk/lib/init-templates/v2/sample-app/python/app.template.py
• README.md
• packages/aws-cdk/lib/init-templates/v2/sample-app/python/README.template.md
• packages/aws-cdk/lib/init-templates/v2/sample-app/typescript/README.template.md
• packages/aws-cdk/lib/init-templates/v2/app/typescript/README.md

The AWS Cloud Development Kit (CDK) provides a command-line interface (CLI) to bootstrap new projects. The cdk init command creates a new CDK app, which is a project containing one or more stacks. A stack is a unit of deployment, and it is composed of constructs, which represent AWS resources. The sample-app template is specifically designed to demonstrate a basic, working CDK application with a few interconnected AWS resources.

This process allows developers to quickly start defining their cloud infrastructure using familiar programming languages like TypeScript, Python, Java, C#, and Go. The generated project includes all necessary configuration files, a sample stack, and instructions for building, synthesizing, and deploying the application.

Sources: README.md:14-20, README.md:60-63, packages/aws-cdk/lib/init.ts:25-29

Project Initialization (cdk init)

The primary mechanism for creating a new CDK application is the cdk init command. When run, it initializes a project structure based on a specified template and programming language.

Sources: README.md:60-63, packages/aws-cdk/lib/init.ts:25-29

Command Usage

To create a new sample application, you use the following command:

$ mkdir hello-cdk
$ cd hello-cdk
$ cdk init sample-app --language=typescript

This command initializes a new project in the hello-cdk directory using the sample-app template for the TypeScript language. The cliInit function in init.ts handles this logic, selecting the appropriate InitTemplate based on the provided arguments.

Sources: README.md:60-63, packages/aws-cdk/lib/init.ts:25-44

Initialization Flow

The cdk init command follows a specific flow to set up the project. It validates the template and language, installs template files, applies future-feature flags, invokes post-generation hooks, and initializes a Git repository.

The diagram below illustrates the high-level logic of the cliInit function.

The InitTemplate Class

The core of the initialization logic is the InitTemplate class. This class represents a project template, such as app or sample-app. It manages the languages it supports and contains the logic for installing the template files into a target directory. During installation, it replaces placeholders like %name% and %cdk-version% with project-specific values.

This diagram shows the structure of the InitTemplate class, which is responsible for handling the template installation logic.

Sources: packages/aws-cdk/lib/init.ts:70-241

The Sample Application Architecture

The sample-app template creates a simple but functional set of AWS resources to demonstrate how constructs work together. It provisions an Amazon SQS queue and an Amazon SNS topic, then creates a subscription so that any message published to the topic is sent to the queue.

This architecture is defined within the stack class of the generated project.

This diagram shows the resources created by the sample application and their relationship.

Sources: packages/aws-cdk/lib/init-templates/v2/sample-app/typescript/README.template.md:3-4, packages/aws-cdk/lib/init-templates/v2/sample-app/typescript/lib/%name%-stack.template.ts:10-21

TypeScript Stack Definition

In a TypeScript project, the resources are defined in a file like lib/my-project-stack.ts.

// Source: packages/aws-cdk/lib/init-templates/v2/sample-app/typescript/lib/%name%-stack.template.ts:10-21
export class %name.PascalCased%Stack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // The code that defines your stack goes here

    // example resource
    const queue = new sqs.Queue(this, '%name.PascalCased%Queue', {
      visibilityTimeout: cdk.Duration.seconds(300)
    });

    const topic = new sns.Topic(this, '%name.PascalCased%Topic');

    topic.addSubscription(new subs.SqsSubscription(queue));
  }
}

This code snippet shows the instantiation of sqs.Queue and sns.Topic constructs and the creation of a subscription between them.

Sources: packages/aws-cdk/lib/init-templates/v2/sample-app/typescript/lib/%name%-stack.template.ts:10-21

Python Application Structure

In a Python project, the entry point is typically app.py, which instantiates the app and the stack.

# Source: packages/aws-cdk/lib/init-templates/v2/sample-app/python/app.template.py:1-12
#!/usr/bin/env python3
import os

import aws_cdk as cdk

from %name.PythonModule%.%name.PythonModule%_stack import %name.PascalCased%Stack


app = cdk.App()
%name.PascalCased%Stack(app, "%name.PascalCased%Stack",
    # If you don't specify 'env', this stack will be environment-agnostic.
    # Account/Region-dependent features and context lookups will not work,
    # but a single synthesized template can be deployed anywhere.
    )

app.synth()

This file is responsible for creating an instance of the cdk.App and the project's stack class (%name.PascalCased%Stack), and then synthesizing the CloudFormation template by calling app.synth().

Sources: packages/aws-cdk/lib/init-templates/v2/sample-app/python/app.template.py:1-12

Post-Initialization Steps

After the project files are created, cdk init performs several additional steps to ensure the project is ready for development. This includes initializing a Git repository and installing language-specific dependencies.

The following sequence diagram illustrates this process.

This flow ensures that the user gets a fully functional project with version control and all necessary dependencies installed.

Sources: packages/aws-cdk/lib/init.ts:297-368, packages/aws-cdk/lib/init-templates/v2/sample-app/python/README.template.md:25-27

Useful Commands

The generated README.md file in each new project contains a list of useful commands for managing the CDK application. These commands are essential for the development lifecycle.

Command	Language(s)	Description
cdk deploy	All	Deploys the stack to your default AWS account/region.
cdk synth	All	Emits the synthesized CloudFormation template.
cdk diff	All	Compares the deployed stack with the current state.
cdk ls	Python, Java	Lists all stacks in the app.
npm run build	TypeScript	Compiles TypeScript to JavaScript.
npm run test	TypeScript, JavaScript	Performs the Jest unit tests.
pytest	Python	Runs the Pytest unit tests.
mvn package	Java	Compiles and runs tests, packaging the application.

Sources: README.md:73-75, packages/aws-cdk/lib/init-templates/v2/app/typescript/README.md:8-13, packages/aws-cdk/lib/init-templates/v2/sample-app/python/README.template.md:43-48

Conclusion

Creating your first CDK app is a streamlined process thanks to the cdk init command and the sample-app template. This entry point provides a fully configured project with a working example of defining, connecting, and deploying AWS resources using code. By exploring the generated project, developers can quickly grasp the core concepts of the AWS CDK, including apps, stacks, and constructs, and begin building their own cloud infrastructure.

Sources: README.md:50-57, packages/aws-cdk/lib/init.ts:25-29