How to install a specific version of a CDK package

avatar

Borislav Hadzhiev

Mon Apr 05 20212 min read

We can lock down the versions of CDK packages by passing in the --save-exact flag upon installation

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
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
{
  "dependencies": {
    "@aws-cdk/aws-s3": "1.96.0"
  }
}

Discussion #

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
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
{
  "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, 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.

Further Reading #

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee