This repo is boilerplate template for building, debugging and deploying AWS Cloud Development Kit stacks and constructs in Typescript. It works by using a simple file structure to define stacks, optionally pass variables to them from JSON files and proxy commands to the AWS CDK Toolkit cli from npm/yarn scripts.

This repository is a GitHub template, so you can quickly copy it and start tinkering with AWS CDK. Just hit the "Use this template" button on the this repo's GitHub page.

First you need to install the cdk cli globally:

npm install -g aws-cdk
yarn install

Next, you need to created a .env file in the root directory and define the following three variables:

1. AWS_PROFILE: The name of the Named Profile that provides the credentials for your account.
2. AWS_ACCOUNT_ID: Your AWS Account ID number.
3. AWS_REGION: The AWS Region to which the cdk cli will submit api calls.

The file should look something like this:

AWS_PROFILE=spencer
AWS_ACCOUNT_ID=7124579443257
AWS_REGION=us-east-1

To define a stack, create a new .ts file in src/stacks. The filename you choose will become the root name of the stack and you will issue commands to the helper scripts by passing it as an argument. For example, let's create a basic stack called plain-bucket by creating the file src/stack/plain-bucket.ts. It just makes a single S3 bucket:

import { App, Stack, StackProps } from "@aws-cdk/core";

import { Bucket } from "@aws-cdk/aws-s3";

// Your exported class must be named TargetStack
export class TargetStack extends Stack {
    public constructor(scope: App, id: string, props?: StackProps) {
        super(scope, id, props);
        // write your code here
        new Bucket(this, "MyBucket");
    }
}

Now, we can proxy cdk commands to our stack via npm/yarn script in the format: yarn {stack-filename} {cdk command}. For example, let's view the CloudFormation template this stack will create if we used cdk synthesize command. To do this run yarn synthesize plain-bucket. If you are setup correctly, the template will be logged to your console.

To deploy the stack: yarn deploy plain-bucket. CDK will now create a stacked name plain-bucket in your account.

To clean up, destroy the stack: yarn destroy plain-bucket.

Many times will want to create a single stack that accepts options. For example, you may want to create a stack that creates an EC2 instance, but you want it to be different sizes when you deploy it to you your staging or production environments. Let's create a stack similar to the one above, but let's toggle whether the S3 bucket above can be public or not. We will call it poly-bucket.

To do this, we are going to create two envs — public and private — by creating two JSON files inside a subfolder of the env folder that is named after our stack name.

Create env/poly-bucket/public.json:

{
    "isPublic": true
}

Create env/poly-bucket/private.json:

{
    "isPublic": false
}

The filename you choose for the JSON files will passed as the final argument to the npm/yarn scripts. But first let's create our stack file that utilizes the isPublic property of our env files. Create the file src/stacks/poly-bucket.ts:

import { App, Stack, StackProps } from "@aws-cdk/core";

import { Bucket } from "@aws-cdk/aws-s3";

// Your exported class must be named TargetStack
export class TargetStack extends Stack {
    public constructor(scope: App, id: string, props?: StackProps) {
        super(scope, id, props);
        // write your code here
        // access the isPublic property from the JSON file
        const isPublic = scope.node.tryGetContext("isPublic");
        new Bucket(this, "MyBucket", {
            publicReadAccess: isPublic,
        });
    }
}

Now, we can proxy cdk commands to our stack and passed them options via npm/yarn script in the format: yarn {stack-filename} {cdk command} {env-filename}.

If you synthesize the private bucket, the output will be functionally the same as the plain-bucket stack from earlier: yarn synth poly-bucket private.

But the the output from the public bucket will be substantially different: yarn synth poly-bucket public.

Let's deploy the public stack: yarn deploy poly-bucket public. CDK will now create a stacked name poly-bucket-public in your account. The env filename is apended with a hypen the the stack name.

To clean up, destroy the stack: yarn destroy poly-bucket public.