Quick reminder that there is no need to install the Coda SDK globally or modify your system PATH when working with the CLI

The Coda guide for working with the command line (CLI) (as opposed to the web-based Pack Editor) proposes two approaches for installing the SDK (@codahq/packs-sdk node package). The first is to install it globally on your system. The only reason to install it globally is to access to the CLI tool that ships with the SDK when calling the coda command, with no additional setup. Globally installing has a several drawbacks which I won’t go into here.

The guide itself recommends to install the SDK locally (I agree) in the “Single-Project Install” section:

It’s easier to manage dependencies and avoid version conflicts across projects if you create an npm project for your pack and install the SDK and other dependencies locally.

However, the approach suggested by the above guide for the single project install is not ideal IMO. Having to modify your system’s PATH just to use a CLI for one project is not really sustainable. If you have multiple Coda packs in development, your CLI will arbitrarily be the one shipped with the SDK installed for that one pack whose node_modules was added to your PATH. That CLI might be a very different version from the SDK in other packs where you are running coda commands, which can cause compatibility issues and make debugging difficult, as it’s easy to confuse the CLI’s actual version with the version of the SDK listed in your project’s package.json. If you delete or move the project that was pointed to by your PATH, you will have to once more update your PATH to use the CLI. Both approaches also add another onboarding step when installing the project.

These are not problems unique to developing Coda packs, which is why tools like npx exist. With npx, you can simply install the Coda SDK locally (the same way as is indicated in the guide section linked above), but skip the part where you would modify your PATH variable. Instead, simply prefix your coda commands with the npx command/CLI. So for example,

coda upload path/to/pack.ts

would become

npx coda upload path/to/pack.ts

This is also the approach recommended by npm itself: Downloading and installing packages globally | npm Docs. npx comes comes bundled with npm version 5.2+, so there shouldn’t be any other installations required to follow this approach assuming you’ve installed/upgraded the latest npm within the last 4 years (just need to remember to prefix the coda ... commands, otherwise you will get an error like “sh: command not found: coda” from your terminal). If your npm version is < 5.2, you can install npx globally (npm install -g npx), but you should probably just upgrade your npm version :stuck_out_tongue_winking_eye:

1 Like

That’s a great reminder, thanks! The CLI getting started guide uses a local install with npx, but the CLI guide you linked to does assume it’s on the path. Would it have helped to show npx usage there as well?

1 Like

@Eric_Koleda Yes please :slight_smile: Consistency in docs is great. IMO the local install option via npx sounds like the best practice. Disclaimer I’m not a node developer but these types of issues come up in different contexts.

1 Like

Hi Eric, thanks for pointing me towards that documentation link, had not read it before.

Personally I used npx from the start despite reading the other guide, so this post was more meant to be helpful to other devs (I assumed they would necessarily have read the other guide).

Since it is documented both ways I don’t think there is necessarily any change to make, especially since the resource you linked would seem to take precedence.