What does CDK.JSON do in AWS CDK

# The purpose of CDK.JSON in a CDK project

When we initialize a new CDK app with the cdk init command the CDK CLI bootstraps a cdk.json file in the root directory.

Here is an example.

shell

Copied!
mkdir cdk-app
cd cdk-app
npx aws-cdk init app --language=typescript

The contents of the cdk.json file look something similar to the following.

cdk.json

Copied!
{
  "app": "npx ts-node --prefer-ts-exts bin/cdk-app.ts",
  "context": {
    "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
    // ...rest
  }
}

First, we have the app key, which points to a command telling the CDK CLI how to execute our CDK code.

shell

Copied!
npx ts-node --prefer-ts-exts bin/cdk-app.ts

The bin/cdk-app.ts file is where our CDK App and stacks are instantiated, it's the entry point of our CDK application:

bin/cdk-app.ts

Copied!
const app = new cdk.App();

new CdkAppStack(app, 'cdk-stack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

This example was initialized using TypeScript so our code has to be compiled down to JavaScript before it can be executed. That's exactly what the ts-node command does.

The value of the app key is going to be programming language-specific.

Next, we have the context key. Context is a combination of key-value pairs that we can set in our CDK application.

CDK uses context to keep track of the so-called feature flags. Feature flags enable the CDK team to push new features that introduce breaking changes, outside of major version releases.

The feature flags point to a boolean value, i.e.:

cdk.json

Copied!
{
  "context": {
    "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
  }
}

The name of the feature flag starts with the name of the package that introduces the breaking change.

For new projects, initialized with the cdk init command, the value of all feature flags is set to true.

However, if we're working on an existing project we can decide for ourselves if we want to opt in after we research, whether this feature or bug fix might cause breaking changes in our CDK application.

Another property that's available in the cdk.json file is the versionReporting property.

cdk.json

Copied!
{
  // 👇 turn off metadata reporting
  "versionReporting": false,
  "app": "npx ts-node --prefer-ts-exts infra/app.ts",
  "context": {
    "@aws-cdk/core:enableStackNameDuplicates": "true",
    // ... rest
  }
}

The versionReporting property allows us to turn off Metadata Reporting in CDK.

In short, Metadata is a CloudFormation feature that allows us to specify additional details about our template.

The CDK team uses Metadata to collect analytics in regard to how developers use the CDK service.

I have nothing against that, however, I don't like having any extra stuff in my CloudFormation templates.

When we run the cdk synth command the CDK CLI generates a CloudFormation template in the cdk.out directory.

It's a matter of personal preference, judge for yourself.

Template with metadata:

cdk out metadata

Template without metadata:

cdk out no metadata

I've also written an article on what CDK bootstrap does.

# Summary

The two main objectives of the cdk.json file are:

to tell the CDK CLI how to execute our CDK code.
and keep track of feature flags, which enable the CDK team to safely roll out new features and bug fixes that cause breaking changes.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.

You can use the search field on my Home Page to filter through all of my articles.

What does CDK.JSON do in AWS CDK

# The purpose of CDK.JSON in a CDK project

# Summary

# Additional Resources

Borislav Hadzhiev