How to install a specific version of a CDK package

Install Specific CDK package Version #

In order to install a specific version of a package, we need to append the --save-exact flag to the npm install command.

shell

Copied!
npm install --save-exact @aws-cdk/aws-s3@1.96.0

This way we were able to lock the version down in our package.json:

package.json

Copied!
{
  "dependencies": {
    "@aws-cdk/aws-s3": "1.96.0"
  }
}

Discussion #

Note that most of the information in this article relates to CDK version 1. In CDK v1, we have a monolithic package that only contains stable APIs.

If the versions of our CDK packages diverge we start getting error messages.

Unable to determine cloud assembly output directory. Assets must be defined indirectly within a "Stage" or an "App" scope

The default behavior when installing a package using npm is that the package versions get prefixed with a ^ (caret) symbol:

shell

Copied!
npm install @aws-cdk/aws-s3@1.96.0

The result is that the version of the package is not locked down in our package.json:

package.json

Copied!
{
  "dependencies": {
    "@aws-cdk/aws-s3": "^1.96.0"
    }
}

Npm packages follow semantic versioning. The version numbers are in the form of major.minor.patch.

The ^ (caret) symbol tells npm - when someone runs npm install, install either 1.96.0 or the latest minor or patch version, i.e. 1.99.0.

This can lead to inconsistent behavior, especially due to the fact that many of the CDK Constructs are in an experimental state, don't follow semantic versioning and introduce breaking changes with minor and patch version updates.

Something to keep in mind is that if we rely on a globally installed version of the CDK CLI, the version of the CDK CLI has to be higher than the versions of the locally installed in our project packages.

It's a terrible idea to rely on a globally installed aws-cdk version, especially when collaborating with others because it's just one more thing to keep in mind, to always keep your global version higher than the version of the locally installed packages.

If you forget to update the global version when you update your local versions, you end up getting cryptic errors that are hard to debug.

If you want to read more about CDK version management, check out my other article - How to manage Package Versions in AWS CDK.

How to install a specific version of a CDK package

Install Specific CDK package Version #

Discussion #

Further Reading #

Borislav Hadzhiev