vp env pin: update an existing .nvmrc instead of adding devEngines.runtime

[ywenhao]

Description

When a project's only Node.js version declaration is an existing .nvmrc, vp env pin lts should update that file by default. In Vite+ 0.3.1, it instead adds package.json#devEngines.runtime and leaves .nvmrc unchanged.

This turns one Node version declaration into two conflicting declarations. Vite+ immediately switches to the new devEngines.runtime value because it has higher priority, while nvm and CI jobs configured with node-version-file: .nvmrc still read the old version.

The requested behavior is to retain the project's existing version-management format when changing its pin. Implementation PR: #2676.

Reproduction

Reproduced with the published vp v0.3.1 binary on Linux x64 / WSL2, in a temporary directory with no dependencies or local Vite+ installation:

repro_dir="$(mktemp -d)"
cd "$repro_dir"
cat > package.json <<'JSON'
{
  "name": "vp-pin-nvmrc-repro",
  "private": true
}
JSON
printf '24.20.0\n' > .nvmrc

vp env current --json
vp env pin lts --no-install
cat .nvmrc
cat package.json
vp env current --json

--no-install only avoids pre-downloading the runtime. In this reproduction, lts resolved to 24.21.0.

Before pinning, vp env current --json reports:

{ "node": { "version": "24.20.0", "source": ".nvmrc" } }

The pin command reports:

✓ Pinned Node.js version to 24.21.0 (resolved from lts)
  Updated devEngines.runtime in <repro>/package.json

.nvmrc still contains 24.20.0, while package.json now contains:

{
  "name": "vp-pin-nvmrc-repro",
  "private": true,
  "devEngines": {
    "runtime": {
      "name": "node",
      "version": "24.21.0",
      "onFail": "download"
    }
  }
}

After pinning, vp env current --json reports:

{ "node": { "version": "24.21.0", "source": "devEngines.runtime" } }

The two JSON outputs above are excerpts containing the relevant fields.

Suggested solution

When .nvmrc is the existing, sole Node pin in the current project and no explicit --target is supplied:

• Update .nvmrc to the resolved version (24.21.0 in this example).
• Leave package.json unchanged and avoid creating another Node version declaration.
• Preserve an explicit --target dev-engines choice for users who intentionally want that format. A --target nvmrc option could also make the choice explicit.

This would extend the existing compatibility-first behavior for .node-version. As a control, the same fixture with .node-version instead of .nvmrc, using vp env pin lts --no-install --force, updates .node-version and leaves package.json unchanged.

Alternative

Manually editing .nvmrc works, but bypasses the pin command. --target node-version creates a second version file, so it does not preserve the existing setup. Removing .nvmrc or migrating the project to another format can disrupt teammates and CI that still use it.

Additional context

• Support .nvmrc as a source for node version #2207 / feat: add support for .nvmrc as node version source #2244 added support for reading .nvmrc. This request concerns writing/updating the existing file during vp env pin.
• The current pin target selection in v0.3.1 checks .node-version and package.json, but does not consider .nvmrc.
• I checked open and closed issues/PRs for .nvmrc, env pin, existing pins, and write-target selection, and did not find a report requesting this behavior.

Validations

• Read the Contributing Guidelines.
• Confirm this request is for Vite+ itself and not an underlying tool.
• Check that there isn't already an issue requesting the same feature.

[fengmk2]

@ywenhao I just suddenly remembered that vp migrate would suggest converting .nvmrc to .node-version, what's the reason your project can only continue using the .nvmrc configuration?

[ywenhao]

@fengmk2 Thanks for pointing that out. My main concern is preserving the existing configuration when updating the Node version.

vp migrate is an explicit migration operation, so converting .nvmrc to .node-version makes sense there. When running vp env pin lts, I expect to update the version in the file the project already uses.

Currently, Vite+ reads .nvmrc, but pinning adds a higher-priority devEngines.runtime declaration while leaving .nvmrc unchanged. That creates two potentially conflicting version declarations.

PR #2676 extends the existing “update the current pin” behavior to .nvmrc, without changing resolution priority. The motivation is consistency for projects that haven’t chosen to migrate their configuration format, rather than a claim that my project is technically unable to migrate.