fix(self-update): refresh legacy v10 bootstrap shim at PNPM_HOME by zkochan · Pull Request #11467 · pnpm/pnpm

zkochan · 2026-05-05T10:56:47Z

Summary

Closes Regression: pnpm 11.x on Windows installs self-update into global/v11 but does not update bootstrap loader in %LOCALAPPDATA%\pnpm #11464.
pnpm v10 setup added PNPM_HOME directly to PATH and wrote a pnpm bootstrap shim there. v11 setup writes shims under PNPM_HOME/bin instead, so when a v10 user upgrades to v11 the legacy shim at PNPM_HOME keeps pointing into the old .tools/<version> install — pnpm --version continues to report the pre-update version even though the new version was installed under global/v11.
Self-update now detects the v10 layout (presence of PNPM_HOME/pnpm or PNPM_HOME/pnpm.cmd, which a fresh v11 setup never writes), refreshes those shims so the upgrade actually takes effect for users still on the v10 PATH, and prints a hint suggesting pnpm setup to migrate PATH to the v11 layout.

Test plan

New unit test: legacy v10 shim at pnpmHomeDir gets refreshed; pnpm -v resolved via PATH = pnpmHomeDir (the v10 layout) returns the freshly installed version.
New unit test: clean v11 layouts are not polluted — self-update does not start writing shims at pnpmHomeDir when no legacy marker is present.
All 39 tests in selfUpdate.test.ts pass.
pnpm run lint clean.

Summary by CodeRabbit

Bug Fixes
- Fixed pnpm self-update when upgrading from v10 installations. The command now detects and refreshes legacy v10 shims, ensuring the new version is properly reflected. Users receive guidance to run pnpm setup for final migration.

pnpm v10 setup added PNPM_HOME (not PNPM_HOME/bin) to PATH and wrote a pnpm bootstrap shim there. After upgrading to v11, that shim still points into the old .tools/<version> install, so PATH continues to resolve `pnpm` to the pre-update version even though the new version was installed under global/v11. Detect that layout during self-update, refresh the shims at PNPM_HOME so the upgrade actually takes effect, and warn the user to run `pnpm setup` for a clean migration to the v11 PATH layout. Closes #11464.

coderabbitai · 2026-05-05T10:57:01Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e634b52b-13f1-4b7b-9718-808b5db51758

📥 Commits

Reviewing files that changed from the base of the PR and between e51c8e2 and 3ddfe77.

📒 Files selected for processing (3)

.changeset/self-update-refresh-v10-shim.md
engine/pm/commands/src/self-updater/selfUpdate.ts
engine/pm/commands/test/self-updater/selfUpdate.test.ts

📝 Walkthrough

Walkthrough

This PR fixes a regression in pnpm v11 where pnpm self-update upgrading from v10 installations failed to update legacy bootstrap shims at PNPM_HOME. The fix detects the legacy v10 layout (shim files directly under PNPM_HOME), refreshes those shims to point to the new v11 installation, and prompts users to run pnpm setup for full PATH migration.

Changes

Legacy v10 Shim Refresh on Self-Update

Layer / File(s)	Summary
Release Metadata `.changeset/self-update-refresh-v10-shim.md`	Declares patch releases for `@pnpm/engine.pm.commands` and `pnpm` with a summary of the v10→v11 shim refresh fix and issue reference.
Core Implementation `engine/pm/commands/src/self-updater/selfUpdate.ts`	Adds `hasLegacyHomeDirShim()` helper to detect v10 layout by checking for `pnpm` and `pnpm.cmd` files at `PNPM_HOME`. Replaces unconditional bin-linking with conditional logic: if legacy layout exists, refresh shims at `PNPM_HOME` and warn user to run `pnpm setup`; otherwise use v11 `PNPM_HOME/bin` layout.
Test Coverage `engine/pm/commands/test/self-updater/selfUpdate.test.ts`	Adds two test cases: one verifies legacy v10 shim refresh correctly resolves to the new version when `PNPM_HOME` is on `PATH`; the other confirms v11 clean layout does not create shims at `PNPM_HOME` root.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

pnpm/pnpm#11435: Modifies the same selfUpdate.ts handler to add downgrade-prevention logic alongside this legacy shim refresh feature.

Poem

🐰 A rabbit hops through versioned lands,
Where old v10 shims once took their stand.
"Refresh!" cried v11 with glee,
Now legacy bootstraps point where they should be.
pnpm setup whispers the gentle way,
To migrate the PATH and brighten the day! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing self-update to refresh legacy v10 bootstrap shims at PNPM_HOME.
Linked Issues check	✅ Passed	The PR fully addresses issue `#11464` by detecting v10 legacy layout, refreshing bootstrap shims, and providing migration guidance to users.
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing self-update behavior for v10-to-v11 migration; no unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/11464

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

This PR fixes a self-update regression for users who originally installed pnpm with the v10 PNPM_HOME layout. It keeps self-update compatible with that legacy bootstrap location while preserving the v11 PNPM_HOME/bin layout as the current standard.

Changes:

Detects legacy v10-style shims located directly under PNPM_HOME during pnpm self-update.
Refreshes those legacy shims after installing the new version, and emits a migration hint to run pnpm setup.
Adds tests covering both legacy-layout refresh and the clean v11 case where no root-level shims should be created.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
`engine/pm/commands/src/self-updater/selfUpdate.ts`	Adds legacy shim detection, refresh logic, and a migration warning during self-update.
`engine/pm/commands/test/self-updater/selfUpdate.test.ts`	Adds regression tests for legacy v10 `PNPM_HOME` shims and verifies clean v11 layouts stay untouched.
`.changeset/self-update-refresh-v10-shim.md`	Documents the self-update fix and its user-visible behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

) pnpm v10 setup added PNPM_HOME (not PNPM_HOME/bin) to PATH and wrote a pnpm bootstrap shim there. After upgrading to v11, that shim still points into the old .tools/<version> install, so PATH continues to resolve `pnpm` to the pre-update version even though the new version was installed under global/v11. Detect that layout during self-update, refresh the shims at PNPM_HOME so the upgrade actually takes effect, and warn the user to run `pnpm setup` for a clean migration to the v11 PATH layout. Closes #11464.

Copilot AI review requested due to automatic review settings May 5, 2026 10:56

Copilot started reviewing on behalf of zkochan May 5, 2026 10:57 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

zkochan added this to the v11.0 milestone May 5, 2026

zkochan merged commit d351d52 into main May 5, 2026
17 checks passed

zkochan deleted the fix/11464 branch May 5, 2026 11:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(self-update): refresh legacy v10 bootstrap shim at PNPM_HOME#11467

fix(self-update): refresh legacy v10 bootstrap shim at PNPM_HOME#11467
zkochan merged 1 commit into
mainfrom
fix/11464

zkochan commented May 5, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 5, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

zkochan commented May 5, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zkochan commented May 5, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 5, 2026 •

edited

Loading