fix(config): allow user-level preferences in global config.yaml by zkochan · Pull Request #11477 · pnpm/pnpm

zkochan · 2026-05-05T20:00:25Z

Summary

Moves 20 user-level preference settings from the workspace-only exclusion list into the global config allowlist (config/reader/src/configFileKey.ts):

Shell / scripts: scriptShell, shellEmulator
Notifications & UI: updateNotifier, useStderr
Trust policy (already DLX-inherited as user-level posture): trustPolicy, trustPolicyExclude, trustPolicyIgnoreAfter
Store / virtual store: globalVirtualStoreDir, virtualStoreDir, virtualStoreDirMaxLength, verifyStoreIntegrity, sideEffectsCache, sideEffectsCacheReadonly
Build / dep verification: strictDepBuilds, verifyDepsBeforeRun
Misc personal/system prefs: stateDir, registrySupportsTimeField, initPackageManager, initType, agent

These are personal/system preferences rather than workspace structure. In v10 they could be set in ~/.npmrc. v11 silently dropped them from both ~/.npmrc and the new global config.yaml, leaving pnpm-workspace.yaml as the only working location — which the issue author rightly points out is impractical for system-level defaults like scriptShell.

After this change:

Settings in ~/.config/pnpm/config.yaml are applied instead of being filtered out by isConfigFileKey (config/reader/src/index.ts:296).
pnpm config set --location global scriptShell <path> succeeds instead of throwing ConfigSetUnsupportedYamlConfigKeyError (same predicate used in config/commands/src/configSet.ts:237).

pmOnFail and runtimeOnFail are intentionally left workspace-only because they would cause lockfile divergence between contributors when set globally. ~/.npmrc support for non-auth/non-network keys is also intentionally not restored — the team has moved those settings to YAML config.

Closes #11474.

Test plan

tsgo --build — the _proofExcludedPnpmKeysIsExhaustive and _proofNoContradiction static type assertions still hold after the move.
Added regression test in config/reader/test/index.ts (reads user-level preference settings from global config.yaml) that writes 14 of these keys to a global config.yaml and asserts they're applied without warnings.
pnpm run lint passes.
CI green.

Written by an agent (Claude Code, claude-opus-4-7).

Summary by CodeRabbit

New Features
- Expanded global PNPM configuration to support additional user-level preferences, including agent settings, virtual store options, script shell configuration, caching controls, and verification features.
Documentation
- Added documentation for configuring user-level preferences in the global PNPM config file.

Move scriptShell, shellEmulator, updateNotifier, trustPolicy*, globalVirtualStoreDir, stateDir, registrySupportsTimeField, initPackageManager, initType, and agent from the workspace-only exclusion list into the global config allowlist. These are personal/system preferences (not workspace structure), and in v10 they could be set via ~/.npmrc. v11 silently dropped them from both ~/.npmrc and the new global config.yaml, with pnpm-workspace.yaml as the only working location. Closes #11474.

coderabbitai · 2026-05-05T20:00:33Z

📝 Walkthrough

Walkthrough

This PR expands global PNPM configuration support by enabling system-wide preferences in ~/.config/pnpm/config.yaml. It reclassifies configuration keys to allow settings like scriptShell, agent, and stateDir to be read from the global config file, and adds comprehensive test coverage validating the feature.

Changes

Global Config Key Expansion

Layer / File(s)	Summary
Key Declaration `config/reader/src/configFileKey.ts`	`pnpmConfigFileKeys` expanded to include `agent`, `global-virtual-store-dir`, `http-proxy`, `init-package-manager`, `init-type`, `virtual-store-dir`, and `virtual-store-dir-max-length`. `init-package-manager` and `init-type` moved from `excludedPnpmKeys` to allowed file keys. New CLI/workspace-only exclusions added: `shamefully-hoist`, `shared-workspace-lockfile`, `symlink`, `sort`, `stream`, `strict-store-pkg-content-check`, `strict-peer-dependencies`.
Test Coverage `config/reader/test/index.ts`	New test "reads user-level preference settings from global config.yaml" verifies that settings like `scriptShell`, `shellEmulator`, `updateNotifier`, `stateDir`, `trustPolicy`, `registrySupportsTimeField`, `sideEffectsCache`, `strictDepBuilds`, `useStderr`, `verifyDepsBeforeRun`, `verifyStoreIntegrity`, `virtualStoreDir`, and `virtualStoreDirMaxLength` are correctly loaded from global config.
Feature Documentation `.changeset/global-yaml-user-prefs.md`	Changeset documents the feature as patch entries for `@pnpm/config.reader` and `pnpm`, listing all configurable global settings and referencing issue `#11474`.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

pnpm/pnpm#11470: Adds warnings for ignored config keys in global config files; directly related to key classification changes in this PR.

Poem

A rabbit hops with config in hand,
Global settings now command the land,
No more per-project, bash finds its way,
Preferences persist, day after day! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: allowing user-level preferences to be configured in the global config.yaml file.
Linked Issues check	✅ Passed	The PR successfully implements the core requirement from `#11474`: restoring the ability to set personal preferences like scriptShell globally, with 20 settings moved from workspace-only exclusion into the global config allowlist.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to enabling user-level preferences in global config: documentation, configuration key classification updates, and test coverage for the new functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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/11474

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

Move side-effects-cache, side-effects-cache-readonly, strict-dep-builds, use-stderr, verify-deps-before-run, verify-store-integrity, virtual-store-dir, and virtual-store-dir-max-length from the workspace-only exclusion list into the global config allowlist.

coderabbitai

🧹 Nitpick comments (1)

config/reader/test/index.ts (1)
1713-1736: ⚡ Quick win

Assert the full “no warnings” contract.

Line 1736 only filters one warning substring, so this regression still passes if any of these newly allowed keys starts emitting a different warning. Since the expected behavior here is “applies without warnings”, please assert that warnings is empty.
Suggested tightening
-    expect(warnings.find((w) => w.includes('global config file'))).toBeUndefined()
+    expect(warnings).toStrictEqual([])
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@config/reader/test/index.ts` around lines 1713 - 1736, The test currently
only checks that no warning contains "global config file" which misses other
possible warnings; update the assertion on the `warnings` value returned by
`getConfig` to assert it is empty (e.g., replace the `expect(warnings.find((w)
=> w.includes('global config file'))).toBeUndefined()` line with an assertion
that `warnings` is an empty array such as `expect(warnings).toEqual([])` or
`expect(warnings).toHaveLength(0)`), keeping the `getConfig` call and the
`warnings` variable unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@config/reader/test/index.ts`:
- Around line 1713-1736: The test currently only checks that no warning contains
"global config file" which misses other possible warnings; update the assertion
on the `warnings` value returned by `getConfig` to assert it is empty (e.g.,
replace the `expect(warnings.find((w) => w.includes('global config
file'))).toBeUndefined()` line with an assertion that `warnings` is an empty
array such as `expect(warnings).toEqual([])` or
`expect(warnings).toHaveLength(0)`), keeping the `getConfig` call and the
`warnings` variable unchanged.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d2069fd3-e492-4795-9160-0bb3cfe8af5c

📥 Commits

Reviewing files that changed from the base of the PR and between 286018e and a1d34b1.

📒 Files selected for processing (3)

.changeset/global-yaml-user-prefs.md
config/reader/src/configFileKey.ts
config/reader/test/index.ts

Copilot

Pull request overview

Enables a set of user-level preference options to be read from (and written to) the global config.yaml by expanding the global YAML allowlist in @pnpm/config.reader, restoring behavior that previously worked via user-level config in pnpm v10.

Changes:

Added 20 user-level preference keys to the global config.yaml allowlist (pnpmConfigFileKeys) so they are no longer filtered out.
Added a regression test asserting several of these preferences are applied from global config.yaml without triggering “ignored keys” warnings.
Added a changeset to publish the behavior change for @pnpm/config.reader and pnpm.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
config/reader/src/configFileKey.ts	Moves user-preference keys from the excluded list into the global YAML allowlist so they can be set globally.
config/reader/test/index.ts	Adds a regression test verifying select user-preference keys are applied from global `config.yaml` without warnings.
.changeset/global-yaml-user-prefs.md	Documents the newly-supported global `config.yaml` keys and bumps packages with a patch changeset.

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

iki · 2026-05-06T15:09:15Z

Awesome work @zkochan 🔥 Thanks!
I'll test it, when released in 1.0.7 I presume.

From user perspective, it would be great to see on the Settings, what settings are workspace-only, WDYT? Should I create a Feature Request for it?

zkochan · 2026-05-06T15:27:26Z

sounds good

Moves 20 user-level preference settings from the workspace-only exclusion list into the global config allowlist (`config/reader/src/configFileKey.ts`): - Shell / scripts: `scriptShell`, `shellEmulator` - Notifications & UI: `updateNotifier`, `useStderr` - Trust policy (already DLX-inherited as user-level posture): `trustPolicy`, `trustPolicyExclude`, `trustPolicyIgnoreAfter` - Store / virtual store: `globalVirtualStoreDir`, `virtualStoreDir`, `virtualStoreDirMaxLength`, `verifyStoreIntegrity`, `sideEffectsCache`, `sideEffectsCacheReadonly` - Build / dep verification: `strictDepBuilds`, `verifyDepsBeforeRun` - Misc personal/system prefs: `stateDir`, `registrySupportsTimeField`, `initPackageManager`, `initType`, `agent` These are personal/system preferences rather than workspace structure. In v10 they could be set in `~/.npmrc`. v11 silently dropped them from both `~/.npmrc` and the new global `config.yaml`, leaving `pnpm-workspace.yaml` as the only working location — which the issue author rightly points out is impractical for system-level defaults like `scriptShell`. After this change: - Settings in `~/.config/pnpm/config.yaml` are applied instead of being filtered out by `isConfigFileKey` (`config/reader/src/index.ts:296`). - `pnpm config set --location global scriptShell <path>` succeeds instead of throwing `ConfigSetUnsupportedYamlConfigKeyError` (same predicate used in `config/commands/src/configSet.ts:237`). `pmOnFail` and `runtimeOnFail` are intentionally left workspace-only because they would cause lockfile divergence between contributors when set globally. `~/.npmrc` support for non-auth/non-network keys is also intentionally not restored — the team has moved those settings to YAML config. Closes #11474.

zkochan marked this pull request as ready for review May 5, 2026 23:03

Copilot AI review requested due to automatic review settings May 5, 2026 23:03

Copilot started reviewing on behalf of zkochan May 5, 2026 23:03 View session

coderabbitai Bot reviewed May 5, 2026

View reviewed changes

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread config/reader/test/index.ts

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

zkochan deleted the fix/11474 branch May 5, 2026 23:44

iki mentioned this pull request May 11, 2026

Docs: Update Settings page to make clear which settings are workspace-only and which can be set globally #11585

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(config): allow user-level preferences in global config.yaml#11477

fix(config): allow user-level preferences in global config.yaml#11477
zkochan merged 2 commits into
mainfrom
fix/11474

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

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

iki commented May 6, 2026 •

edited

Loading

Uh oh!

zkochan commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 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

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

zkochan commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zkochan commented May 5, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 5, 2026 •

edited

Loading

iki commented May 6, 2026 •

edited

Loading