DEV Community

Cover image for Don't run `npm install -g ..`it's a trap!

Posted on

Don't run `npm install -g ..`it's a trap!

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:,

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)
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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


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

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)