I recently ran into a situation where a colleague of mine installed AWS CDK globally:
npm install -g aws-cdk
I don’t blame anyone who does that because the official AWS documentation and their workshops are promoting to install it that way: https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html,
But there is a catch!🫣
Mismatch of version
Let's say you've recently joined a new project, and you don't notice that they have pinned a version of a particular version of a package. Since you have been working with AWS CDK, you installed it globally 3 months ago.
You know it's already installed on your machine. So you're blindly running cdk synth
This CDK CLI is not compatible with the CDK library used by your application. Please upgrade the CLI to the latest version. (Cloud assembly schema version mismatch: Maximum schema version supported is 6.0.0, but found 7.0.0)
Ehm... what's happening? 🤔
Well, according to the message, you simply need to update npm install -g aws-cdk and problem solved.
The AWS CDK community releases so fast (I think every week one release). Meaning if your last CDK project was set up 3 months ago, you are 12 releases behind and breaking changes might be included.
Furthermore, your globally installed cdk- version might not be aligned with the version from your project. Because the system will always prioritize the globally installed version if you're using a UNIX machine (I'm not sure about Windows).
They even mentioned that on their troubleshooting page……)
The binary to the project is inside the node_modules
As a recap, everything which is put into package.json, will be downloaded as dependencies. If you use Cloudflare Workers, its CLI will be downloaded and put into node_modules/bin.
When you want to use it, you can run npx before any wrangler command. That is an alias to run ./node_modules/bin. You can also customize the script - section inside the package.json. e.g.
{
"scripts": {
"dev": "wrangler dev src/index.ts",
"deploy": "wrangler deploy --minify src/index.ts"
}
}
In this case, it will always pick up the CLI from the node_modules/bin.
The same you could do with CDK of course-
{
"scripts": {
"synth": "cdk synth",
"dev": "cdk watch",
"deploy": "cdk deploy"
}
}
If you run npm run synth, it will pick the correct CDK version from the node_modules.
If you want to bootstrap a new CDK project, you should bootstrap it with npx
npx cdk init app --language typescript
That will install the CDK CLI temporarily globally.
Tip: If you have several CDK projects and you don’t want to bloat your machine with many CDK downloads, you should consider pnpm or yarn v2.
If you look into other NodeJS- projects such as Wrangler, SST or Vite, none of them will ever require you to install it globally. Of course, there are exceptions for example using pnpm
Conclusion
When running the cdk - CLI, your OS is trying to look the if the CLI is installed in one of the bin from the $PATH (globally) first.
I have been reading and building some NodeJS/Typescript applications using React, Astro, VueJS, Svelte, and Cloudflare Workers, and none of them is requiring you to install something globally. I don’t know why AWS CDK promotes that as it causes more trouble and guess what all issues are saying delete aws-cdk globally and reinstall it
https://github.com/aws/aws-cdk/issues/11494
https://stackoverflow.com/questions/66565550/how-to-solve-cdk-cli-version-mismatch
https://github.com/aws/aws-cdk/issues/14738
If your terminal is saying it cannot find it, it’s a lie because you need to point it to the node_modules by using npx. It is just an alias for running ./node_modules/bin/cdk.
In general, you should not install an npm package globally as it is probably in your node_modules with the correct version for the project.
If you find a page where it says to run npm install -g it’s a trap.
Top comments (0)