pnpm Provider

Uses pnpm  to manage globally installed Node.js command-line tools — the ones you want available from any directory: serve, tsx, prettier, and so on.

Why pnpm specifically, when there’s an npm provider too? Two reasons: pnpm’s global installs are hard-linked (saves a lot of disk), and it doesn’t dump node_modules into system paths the way npm can. If you already use pnpm for project dependencies, matching it for globals keeps things consistent.

Platforms: macOS, Linux

Usage

# Install a global tool
hams pnpm add serve
 
# Remove
hams pnpm remove serve
 
# See what hams is managing
hams pnpm list

The verbs are add / remove, same as native pnpm — no need to remember a different syntax.

Hamsfile example

# macOS/pnpm.hams.yaml
schema_version: 1
provider: pnpm
 
groups:
  - tag: dev
    items:
      - app: serve
        intro: Static file serving and directory listing.
      - app: tsx
        intro: TypeScript executor for Node.js.
      - app: prettier
        tags: [formatter]
        intro: Opinionated code formatter.

app is the npm package name, exactly as you’d write it in pnpm add -g <name>.

How state is probed

hams calls pnpm list -g --depth=0 --json and pulls the globally-installed names and versions out of the JSON. Much more reliable than scraping text output — if pnpm changes how its table renders, hams doesn’t suddenly break.

Bootstrap

Fresh machine without pnpm? hams can install it for you. Pass --bootstrap to apply and hams runs npm install -g pnpm under your consent:

hams apply --bootstrap --from-repo=you/hams-store

On an interactive terminal without the flag, hams shows you the exact command and asks [y/N/s]. On a non-TTY (CI, pipe) without the flag, hams exits with an actionable error naming the missing binary + the install script + the --bootstrap remedy. See hams apply → About the bootstrap prompt for the full rationale.

npm must already be on PATH for npm install -g pnpm to work — bootstrap of the node runtime itself is user-owned (pick nvm / fnm / n / volta / distro as fits your setup).

If you prefer a different pnpm installer (e.g. the standalone curl -fsSL https://get.pnpm.io/install.sh | sh -), use a one-shot bash provider step instead:

# bash.hams.yaml
- urn: "urn:hams:bash:install-pnpm"
  step: Install pnpm
  run: curl -fsSL https://get.pnpm.io/install.sh | sh -
  check: command -v pnpm

pnpm vs npm

Mechanically, both providers do the same thing — the only difference is which tool they wrap. You can even use both in parallel on the same machine: prettier under pnpm, nodemon under npm. Each Hamsfile is separate, they don’t collide. That said, picking one and sticking with it is usually wiser — mixing global Node tools across package managers sometimes surfaces Node-ecosystem quirks that have nothing to do with hams.