Moving settings to `pnpm-workspace.yaml` #9037

zkochan · 2025-02-05T00:29:56Z

zkochan
Feb 5, 2025
Maintainer

Currently we use 3 files for configuring pnpm:

We use .npmrc for most of the settings. Mostly simple settings but also some that can be arrays
We also load settings from the pnpm field in package.json. These are mostly more complex settings with arrays and objects.
We also load catalogs from pnpm-workspace.yaml

We need to stop storing settings in package.json as it breaks the fetch command. See related issue: #9033. Moving all settings to the .npmrc ini file is not convenient. The best approach seems to be to move all the settings to pnpm-workspace.yaml. On top of the settings from package.json we may also move all the pnpm-specific settings from .npmrc and only keep auth related settings in .npmrc for npm compatibility.

Some settings may be project-specific. Instead of creating separate configuration files for projects in the workspace, we could create configuration overrides in the root pnpm-workspace.yaml. For instance:

packages:
  - "**"
hoistPattern:
  - eslint
configOverrides:
  - globs:
      - back-end/**
    settings:
      executionEnv:
        nodeVersion: 16.16.0

Related PRs:

npm CLI will disallow 3rd party settings in .npmrc from v12. Related issue: #9232

KSXGitHub · 2025-02-07T12:55:29Z

KSXGitHub
Feb 7, 2025
Collaborator

There are many subtle bugs related to .npmrc and workspace root being at different places. Moving all settings to the workspace manifest would solve this problem.

2 replies

zkochan Feb 7, 2025
Maintainer Author

I was trying to recall settings that can be placed in nested directories but couldn't remember any except the executionEnv.nodeVersion

KSXGitHub Feb 7, 2025
Collaborator

It's usually fine when the there is only one .npmrc at the workspace root. But sometimes, the monorepo doesn't have a .npmrc, but the home directory has one. This causes problem.

gluxon · 2025-02-17T04:34:15Z

gluxon
Feb 17, 2025
Collaborator

This is a good idea! We've hit a lot of strange issues when reusing .npmrc. Ex: #6701

1 reply

zkochan Feb 22, 2025
Maintainer Author

Moving the settings from .npmrc will be a bit complicated unless we will give them more priority then the settings set via npm_config_ env variables. Which might be OK.

zkochan · 2025-03-04T14:07:09Z

zkochan
Mar 4, 2025
Maintainer Author

I would like to also make it possible to share settings via configurational dependencies. I think the easiest and most powerful way to do it would be via introducing a new hook for config settings that could read the existing settings and extend/change them.

0 replies

michkot · 2026-01-26T13:17:21Z

michkot
Jan 26, 2026

What if I don't want any workspace, I want stand-alone project, but I need configuration?

I couldn't figure it out.

Bellow all done with pnpm 10.28.1 (behind corepack, but I verified the first examples without corepack to be sure, same results)

Currently I have this, and I cannot make it work:

x/package.json
x/pnpm-workspace.yaml , instead of .npmrc, with configurations for project x/ (I do NOT want it to be considered a workspace root, at best, I want it to be a single-project workspace).
lockfile and node_modules in x/
x/template/package.json --- template for projects being scaffolded
x/template/pnpm-workspace.yaml , instead of .npmrc, with configurations for the project being scaffolded (should NOT be a workspace semantically)
x/test/package.json (a file to test something, possibly generated by test automation; no workspace file, as no configuration was needed)
in x/test/ i run pnpm install

(Yes, I am aware that nesting node projects during development like this is prone to issues due to the recursive nature of node_modules search)

I observed

trying to do something inside x/template is applied only to x/template, as it sees the nearest workspace file in x/template.
Btw, is nesting pnpm-workspace.yaml officially supported, and what is intended semantics?
calling pnpm commands in x/test sees the workspace file in x/, and behaves weirdly. pnpm i does do ABSOLUTELY NOTHING.

I did try a lot of things, of which i wrote 15% before I stopped, as it already made the post way tooo long. TL;DR, in x/test/

pnpm i does nothing.
pnpm i|add <package> forces the install of that one package and accompanying entry in x/ lock-file, but afterwards deleting local node_modules and running pnpm i does still nothing
contrary to the documentation, https://pnpm.io/10.x/pnpm-workspace_yaml, empty workspace file does NOT mean all subdir packages are part of workspace; empty workspace file means workspace of ONLY THE ROOT package?!
behavior of pnpm i and pnpm ls -rand pnpmandpnpm ls -r --depth -1` is out of sync
when doing changes to project configuration like sharedWorkspaceLockfile , it is often necessary to delete node_modules (or at least something in it), just running install and deleting visible pnpm-lock.yaml is not enough to trigger application of the change?

In the end, I gave up mid-way trying a lot of stuff with yaml workspace config, usually running (rm -rf node_modules/ ../pnpm-lock.yaml ../node_modules/ ; pnpm i) between attempts and my conclusion is:

if you want projects to be correctly part of workspace, you have to explicitly add a pattern for it
if you start use pnpm (at v10), you should scaffold all projects (by default, i want them standalone) with empty pnpm-workspace.yaml alongside package.json, to ensure a wrong workspace file is not detected accidentally

P.S. pnpm i --loglevel debug, the loglevel option did not do anything, only --repoter ndjson worked. Is that intended?

1 reply

michkot Jan 26, 2026

Some of my draft text, not 100% precise I as I realized that leaving node_modules and lockfiles in between iterations does skew results

What came next was a bit surprising - I tried setting

packages:
  - "."

inside x/pnpm-workspace.yaml and expected it to fix the problem... nope.

Running pnpm i --reporter ndjson revealed this (redacted, all absolute paths leading to folder x replaced with x

{...,"level":"debug","name":"pnpm:scope","selected":1,"total":1,"workspacePrefix":"x"}
{...,"level":"debug","name":"pnpm:package-manifest","initial":{"name":"<the project in x/>","....,"prefix":"x"}      
{...,"level":"debug","name":"pnpm:context","currentLockfileExists":true,"storeDir":"C:\\Users\\XXX\\AppData\\Local\\pnpm\\store\\v10","virtualStoreDir":"x\\node_modules\\.pnpm"}
{...,"level":"debug","name":"pnpm:stage","prefix":"x","stage":"resolution_started"}

So I guess, pnpm doesn't even consider that the package in CWD is not part of a workspace based on the workspace definition.. Even though it ought to check stuff like sharedWorkspaceLockfile: false

In the end, I tried all of following combinations (took a while :/), and the conclusion was quite bad: If I really want to deploy pnpm widely, I need need to start scaffolding all of projects, even those generated by e.g. test automation, with empty pnpm-workspace.yaml to ensure they are treated as their own one-project mono repo, in case somebody adds pnpm-workspace.yaml file to define configurations (not meant to declare a workspace) in any folder above.:

for yaml config in x/, commands run inside the folder x/test/

id	yaml	command	result
1		pnpm i	installed all stuff from x/ workspace, created lockfile and node_modules in x/, the lockfile mentions x/test + created node_modules in x/test/ with the one dependency that belongs there
2	packages: - "."	same	same
3	packages: - "." - "test"	same	same
4	sharedWorkspaceLockfile: false	same	same
5	sharedWorkspaceLockfile: false packages: - "."	same	same
6	sharedWorkspaceLockfile: false packages: - "." - "test"	same	as before, but with separate lockfile created in x/test
Cell	Cell	Cell
Cell	Cell	Cell

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

pnpm

Moving settings to `pnpm-workspace.yaml` #9037

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 4 comments 4 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

pnpm

Moving settings to pnpm-workspace.yaml #9037

Uh oh!

Uh oh!

zkochan Feb 5, 2025 Maintainer

Replies: 4 comments · 4 replies

Uh oh!

KSXGitHub Feb 7, 2025 Collaborator

Uh oh!

zkochan Feb 7, 2025 Maintainer Author

Uh oh!

KSXGitHub Feb 7, 2025 Collaborator

Uh oh!

gluxon Feb 17, 2025 Collaborator

Uh oh!

zkochan Feb 22, 2025 Maintainer Author

Uh oh!

zkochan Mar 4, 2025 Maintainer Author

Uh oh!

michkot Jan 26, 2026

Uh oh!

michkot Jan 26, 2026

Moving settings to `pnpm-workspace.yaml` #9037

zkochan
Feb 5, 2025
Maintainer

Replies: 4 comments 4 replies

KSXGitHub
Feb 7, 2025
Collaborator

zkochan Feb 7, 2025
Maintainer Author

KSXGitHub Feb 7, 2025
Collaborator

gluxon
Feb 17, 2025
Collaborator

zkochan Feb 22, 2025
Maintainer Author

zkochan
Mar 4, 2025
Maintainer Author

michkot
Jan 26, 2026