AWS CDK is splitting Construct Library and CLI

AWS CDK is an open source software development framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation. It consists of two primary components: the Construct Library that you use in a programming language to model your AWS application, and a CLI. The Construct Library “synthesizes” a model of your application to a directory on disk, and the CLI reads that directory’s files to deploy your application to AWS.

Starting February 2025, the CDK CLI and the CDK Construct Library will no longer be released in lockstep. Instead, they will both have their own independent release cadence, which means their version numbers are going to diverge. There will be no impact to the CDK API or user experience.

This will not fundamentally change the way CDK works or how you use CDK: the newest version of the CLI will always support all versions of the CDK Construct Library that were released before it. You can continue to freely upgrade the CLI to the latest version whenever you want. The biggest difference resulting from this change is that we are moving the source code of the CLI and related components to a new GitHub repository. The new repository will be https://github.com/aws/aws-cdk-cli, and it will be opened up to the public after the migration is done.

The first new version of the CDK CLI on the new version line will be released as 2.1000.0, the next one as 2.1001.0, etc. The CDK Construct Library will continue its current version line, releasing as 2.174.0, 2.175.0, 2.176.0, etc.

Why are we changing this?

The CDK CLI and CDK Construct Library were always separate parts of the CDK development framework. They were historically located in the same repository because that made it easier and faster for us to iterate. Now that CDK has matured, we’ve found that changes to the different components proceed at different paces and require different testing strategies. This change will also give us the ability to make changes to the release cadence of one subproject without affecting the other one, which will give the entire project more agility.

The fundamental compatibility model of the CLI remains the same: a CLI can process the output of all Construct Libraries released with it or before it. This used to manifest as the rule that CLI version >= Lib version is always a valid combination of versions. Because the versions will no longer be released in lockstep, the new rule will be CLI release date >= Lib release date. It will be not as easy to spot that information at a glance from the version number, but we will include the minimum required CLI version number in the cdk.out manifest, so that the error message includes the required version and publishes a table with the compatibility information of every version to GitHub.

To indicate a break in the version line continuity, we will leave a large and obvious break in the version numbers of the CLI. After version 2.174.0 , the CLI will skip to 2.1000.0 then proceed to 2.1001.0. Hopefully, this will make it obvious that the version lines are no longer related without us changing the major version number.

CDK Construct Library will continue its current version line, releasing as 2.175.0, 2.176.0, and so on.

What are we not changing?

We are not changing the major version number: We are not releasing CDK CLI 3.x to signify this break in versioning continuity, for two reasons:

• Most customers will have a dependency range like "aws-cdk": "^2.174.0" in their projects. If we changed the major version number to 3.x those projects would stop automatically consuming CLI updates, resulting in a CLI compatibilty error at the next schema change. By remaining in major version 2, new releases will continue to match the specified dependency range and be automatically installed.
• To avoid any chance of interpreting this as a “CDKv3” release—something this change does not represent—we will not change the major version of the CLI to 3 yet. This is not a promise that we will never raise the major version number of the CLI. If there is a good reason to change it in the future, we might do so after all. If we do, we will do so in a way that causes minimal impact. At the very least, any future CLI v3 will remain compatible with non-deprecated 2.x versions of the construct library.

We are not changing where you go to file issues: Even though the CDK CLI code will move to a different repository, and Pull Requests will have to be filed against that other repository, you can continue to file any issues against CDK on the main aws/aws-cdk repository. We want to make it easy for you to have a single place to report issues with the broader CDK framework, regardless of what component they originate from. The AWS CDK teams will monitor issues across all repositories, and move issues to a different repository if necessary. This is the same operating procedure as the one we employ for other CDK components, like jsii.

We are not changing the compatibility model: The compatibility model is not changing. CLIs will always be able to read all cdk.out directories produced by non-deprecated versions of Construct Libraries released before them. To ensure compatibility, we recommend that you npm upgrade your CLI version at least as often as you upgrade your Construct Library version.

Here are a couple of helpful hints you can use to ensure compatibility. A simple rule to follow would be that CLI release date >= Lib release date is guaranteed to work. A more complex but still correct rule to follow is that the most recent CLI release before a lib release is guaranteed to work, and anything newer as well. Older versions might work as well if no changes were made to the format of the files in the cdk.out directory, but that compatibility is not guaranteed.

What is the impact to you?

As a CDK user: You will notice that the versions of the CDK CLI and the CDK Construct Library are no longer the same. We recommend that you think of the version of the CDK Construct Library as “the” version of CDK, because that is the version that will impact your day-to-day experience with CDK the most. We also recommend that you keep your CDK CLI version at the latest version to make sure you always have a CLI version that supports the Construct Library version you are using. Any scripts that assume that there is a single “CDK version” that you can install both the Construct Library and the CLI under, will need to be rewritten:

# This no longer works, there will be two different versions
$ CDK_VERSION=2.714.0
$ npm install aws-cdk-lib@$CDK_VERSION
$ npm install aws-cdk@$CDK_VERSION
# Do this instead (install the latest 2.x)
$ npm install aws-cdk@^2

As a CDK contributor: CLI-related issues should continue to be filed in the aws-cdk repository, but you will need to make any Pull Requests to the new repository. Changes that involve both the CLI and the construct library will need to be sent to both repositories, and merged separately. The CLI change will need to be released before the construct library PR can be merged. The exact workflow is described in the new https://github.com/aws/aws-cdk-cli repository.

Conclusion

We’re excited about being able to improve CDK at a faster rate as a result of this change. We expect the user impact to be minimal, though we know it may require preparation or script updates from our customers. If you have questions or want to join the discussion of the change, see the GitHub Issue discussing it, or reach out to us directly via AWS Support or on Slack.