Don't run `npm install -g ..`it's a trap!
Tags: node, aws, devrel
Published: 2023-08-16 05:30:01


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](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`

```sh
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.

![](https://assets.vrite.io/646ce5fc07ef9ba4530fd23b/PgvIxTmOKUkQlM6pw0e6i.jpeg)

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](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html#troubleshooting_toolkit)[…](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html#troubleshooting_toolkit)…)

## 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](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) 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.

```json
{
  "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-

```json
{
    "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](https://pnpm.io/) or [yarn v2](https://pnpm.io/).
>

If you look into other NodeJS- projects such as Wrangler, [SST](https://sst.dev/) or [Vite](https://sst.dev/), none of them will ever require you to install it globally. Of course, there are exceptions for example using [pnpm](https://sst.dev/)

## 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://github.com/aws/aws-cdk/issues/11494)

[https://stackoverflow.com/questions/66565550/how-to-solve-cdk-cli-version-mismatch](https://stackoverflow.com/questions/66565550/how-to-solve-cdk-cli-version-mismatch)

[https://github.com/aws/aws-cdk/issues/14738](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.