Support `vp env` to manage node version

[hyfdev]

Behavior about managing global binary

Stutus Quo

fnm

• fnm itself doesn't manage global binary. It just relies on npm install -g.
• Global binaries installed by npm install -g will be cleaned up after switching global node version
• fnm use/install is used to install different node

mise

• Same behavior as fnm for global binaries installed by npm install -g
• Global binaries installed by mise use -g .. won't be cleaned up after switching global node version
• mise install is used to install different node

Current proposal for vite-plus

• Same behavior as fnm for global binaries installed by npm install -g

Questions

• What command will us used for installing/switching between node versions?

If we refer to fnm, probably we'll use vp env use/install.

• What command will us used for installing global binary isolately

If vp env use/install is smart enough, we could still stick with vp env use/install

Like: vp env install -g @anthropic-ai/claude-code. But in this case, what does vp env install @anthropic-ai/claude-code mean?

• How it's different with vp install -g @anthropic-ai/claude-code vite install -g @anthropic-ai/claude-code

[linear]

VP-170

[hyfdev]

@fengmk2 could you check if I use vp or vite alias correctly? If not, please correct them directly.

[fengmk2]

@hyf0 From now on we only need to remember the vp command; vite will only appear in package.json scripts and in the tasks field of vite.config.ts. 😄

The logic I've currently designed for global package install is to make everything isolated https://github.com/voidzero-dev/vite-plus/blob/vp-env-shims/rfcs/env-command.md#global-package-management

That is, npm install -g [pkg] and vp env install [pkg] follow the same logic, similar to the approach of mise install [pkg] volta install [pkg]. This is the most stable implementation for users who use a node version manager.

[fengmk2]

How it's different with vp install -g @anthropic-ai/claude-code

The command actually invoked by vp install -g @anthropic-ai/claude-code is npm install -g @anthropic-ai/claude-code, so with the current design it will be equivalent to vp env install @anthropic-ai/claude-code

[hyfdev]

I like the behavior of preserving some global binaries between switching nodes. But for keeping all of them, I'm not sure.

I think the current behavior diverged from the mental model of npm i -g for people who're using fnm before. Even for those who don't, this is still not a intuitive behavior. I'll do a investigation about volta and mise's behavior.

[hyfdev]

Some notes:

• binaries installed by npm i -g will disappear is an already knonw behavior of fnm and nvm. This is a already a solid mental model for node users. I don't see a solid reason to break this mental model. How to install global npm tools that are available across all node versions Schniz/fnm#109 also introduce.
• Volta introduces different behavior with an explicitly different command volta install instead of npm i -g.
  • Notice Votal also intercepts npm i -g. For Volta, it's also the same between volta install and npm i -g

  Comparison Table
  ┌───────┬───────────────────────────────────┬──────────────────────────────────────────────────────────┐
  │ Tool  │         Default Behavior          │                   Built-in Workaround                    │
  ├───────┼───────────────────────────────────┼──────────────────────────────────────────────────────────┤
  │ fnm   │ Isolated per-version              │ None (users complain)                                    │
  ├───────┼───────────────────────────────────┼──────────────────────────────────────────────────────────┤
  │ nvm   │ Isolated per-version              │ nvm reinstall-packages to copy from another version      │
  ├───────┼───────────────────────────────────┼──────────────────────────────────────────────────────────┤
  │ mise  │ Isolated per-version              │ .default-npm-packages auto-install, npm backend          │
  ├───────┼───────────────────────────────────┼──────────────────────────────────────────────────────────┤
  │ Volta │ Isolated + pinned to Node version │ Explicit design - volta install with clear communication │
  └───────┴───────────────────────────────────┴──────────────────────────────────────────────────────────┘

My proposal: Do not make npm i -g special

Reasons to Distinguish vp env install from npm i -g

1. Principle of Least Surprise

npm i -g has had the same behavior for 15+ years. Every Node developer knows:

• Global packages go to the current Node version's directory
• Switching Node versions means different global packages

Intercepting and changing this behavior silently violates user expectations. Even Volta, which does intercept, prints note: using Volta to install Yarn — acknowledging it's doing something unexpected.

2. Explicit is Better Than Implicit

• vp env install explicitly says "I want vite-plus to manage this"
• npm i -g should mean "I'm using npm directly"

Users who want isolation should ask for it. Users who want standard npm behavior shouldn't have to learn why their mental model is broken.

3. Migration Path from fnm/nvm

fnm and nvm users have muscle memory: npm i -g installs to current version, packages disappear when switching. This is annoying but understood.

If vite-plus intercepts npm i -g and isolates everything, these users face:

• Unexpected behavior change
• Confusion about where packages actually live
• No way to get the "old" behavior without env vars

4. Debugging and Transparency

When npm i -g does what npm normally does:

• Users can reason about the system
• npm list -g shows what's installed
• Standard npm troubleshooting applies

When intercepted:

• Users don't know what's actually happening
• npm list -g may show different results than expected
• Adds a layer of magic that obscures problems

5. Two Distinct Use Cases Exist

Use case A: "I want typescript globally for this Node version"
→ npm i -g typescript (traditional, per-version)

Use case B: "I want typescript to always work regardless of Node version"
→ vp env install typescript (isolated, pinned)

These are different intents. One command shouldn't try to serve both.

6. Volta's Quirks Are a Warning

Volta intercepts npm i -g, but:

• Updates require volta install (confusing)
• --dry-run flag is ignored (bug from interception complexity)
• pnpm global installs aren't intercepted (inconsistent)

Interception adds complexity and edge cases. Keeping commands separate avoids this.

7. Composability with Other Tools

Some users may want vite-plus only for Node version management, while using other tools (or raw npm) for package management. Interception forces an all-or-nothing approach.

---

Summary: Let npm i -g be npm i -g. Let vp env install be the explicitly better alternative. Users who want isolation will find it; users who don't won't be surprised.