How to add AWS CDK to an existing project

AWS Cloud Development Kit (AWS CDK) provides an appealing approach to developers for defining the infrastructure through the programming languages they are already familiar with. You can check out the docs to find out more about the tool here https://aws.amazon.com/cdk/.

The initialization command of the AWS CDK CLI will create an independent project and, while this is great for quickly getting up and running and learning about a technology, most often than not you will want to integrate it into an already established setup. In that way, you will be able to enforce the same coding guidelines and apply the same build process as for the rest of the code. In this project, we'll go through the steps required to integrate AWS CDK into an existing monorepo workspace managed with Nrwl Nx. I will not dive into the details of how Nx works as this is not relevant for this article and the same steps are valid for different types of projects, but you could find out more about it at https://nx.dev/.

Initial setup

The starting point of the project is a monorepo Nx workspace with a single app called infra generated at the root directory. Here is a GitHub repo with the complete setup https://github.com/alex-vladut/aws-amplify-cdk.

Generate an AWS CDK application

To generate a new AWS CDK application run the following command at the root of your project:

npx cdk init app --language=typescript

which will result in an error:

cdk init cannot be run in a non-empty directory!

To go around this issue we'll have to create a new empty directory e.g. mkdir cdk (could name it whatever you want), move inside it cd cdk, and then rerun the command above for initializing an AWS CDK app. This time it should run successfully and generate a bunch of files for you.

Configuration

Now that the AWS CDK app is generated, we'll want to move some of the files from the cdk directory and adjust them to be properly integrated into our existing project. First, go ahead and move the file /cdk/cdk.json to the root directory and then update it to point to a different entry point AWS CDK CLI will use for synthesizing and deploying your resources:

-  "app": "npx ts-node --prefer-ts-exts bin/cdk.ts",
+  "app": "dist/infra/main.js",

Rather than relying on AWS CDK to build the code, we'll do it through our tools along with all the other apps. In this case, dist directory is the default destination where projects built with Nx will land, but in the same manner, it could be updated to point to a different location.
Next also remove the following lines from the cdk.json file as won't be required:

  ...
-  "watch": {
-    "include": [
-      "**"
-    ],
-    "exclude": [
-      "README.md",
-      "cdk*.json",
-      "**/*.d.ts",
-      "**/*.js",
-      "tsconfig.json",
-      "package*.json",
-      "yarn.lock",
-      "node_modules",
-      "test"
-    ]
-  },
  ...

Let's add the AWS CDK npm packages to our project:

npm i --save-dev aws-cdk
npm i aws-cdk-lib constructs

Then copy the content of the file cdk/bin/cdk.ts into infra/src/main.ts. Copy the file cdk/lib/cdk-stack.ts to infra/src/main/app and update the import in main.ts to correctly point to it.

And with that, we're done with all the configuration required, feel free to delete the cdk directory as none of the remaining files will be needed anymore. Everything should be set up now, so we can go ahead and deploy our resources into the cloud with AWS CDK CLI.

Deployment

Build the infra project to pick up the latest changes:

npm run build infra

and then deploy it by running the following command:

cdk deploy

A quick note here: if it's the first time you're using AWS CDK, before running cdk deploy you'll have to run cdk bootstrap first.

And that's it, your dummy CDK stack should be deployed to the cloud and now you're ready to add more resources to it.