From 1967ac5a708c32a18a4b3bf029611d4e56a1a67f Mon Sep 17 00:00:00 2001 From: Dan Rose Date: Fri, 18 Apr 2025 14:07:43 -0500 Subject: [PATCH 1/4] document difference between pnpm and npm workspaces --- docs/pnpm-vs-npm.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/pnpm-vs-npm.md b/docs/pnpm-vs-npm.md index 04b50d6f2fb5..28641d78a6a2 100644 --- a/docs/pnpm-vs-npm.md +++ b/docs/pnpm-vs-npm.md @@ -50,3 +50,19 @@ instance in the case of a monorepo, you should look at the documentation for [`pnpm -r`]. [`pnpm -r`]: cli/recursive + +## Workspaces + +Pnpm deals with workspaces slightly differently than npm. + +Terminology: +| pnpm | npm | +| -------- | ------- | +| "workspace" | "workspace root" | +| "workspace package" | "workspace" | + +For clarity, we will refer to "workspace root" and "workspace package" + +In npm, there is a `package.json` file in the workspace root. The `"workspaces"` field in this file describes where to look for dependencies. Whenever a package name matches that of a workspace package, it resolves to the workspace package (regardless of the requested version). + +In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. From d56e04ff9dbd695dae1c73f17102ff49caab9dc7 Mon Sep 17 00:00:00 2001 From: Dan Rose Date: Fri, 18 Apr 2025 14:53:40 -0500 Subject: [PATCH 2/4] Update pnpm-vs-npm.md --- docs/pnpm-vs-npm.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/pnpm-vs-npm.md b/docs/pnpm-vs-npm.md index 28641d78a6a2..8ed6a2060d7f 100644 --- a/docs/pnpm-vs-npm.md +++ b/docs/pnpm-vs-npm.md @@ -53,16 +53,12 @@ instance in the case of a monorepo, you should look at the documentation for ## Workspaces -Pnpm deals with workspaces slightly differently than npm. +Pnpm deals with workspaces slightly differently than npm, starting with conflicting terminology: -Terminology: -| pnpm | npm | -| -------- | ------- | -| "workspace" | "workspace root" | -| "workspace package" | "workspace" | +Pnpm uses the term "workspace" to refer to a *collection* of packages, and sometimes the directory containing such packages. Pnpm uses the term "project" to refer to an individial package in the workspace tree (as contrasted to a package retrieved from a package repository like npm). -For clarity, we will refer to "workspace root" and "workspace package" +Npm uses the term "workspace" to refer to the individual packages being co-developed inside a monorepo. The "workspace root" is the package defining which packages are "workspaces" (in the npm sense). -In npm, there is a `package.json` file in the workspace root. The `"workspaces"` field in this file describes where to look for dependencies. Whenever a package name matches that of a workspace package, it resolves to the workspace package (regardless of the requested version). +In npm, there is a `package.json` file in the workspace root. The `"workspaces"` field in this file describes where to look for dependencies. Whenever a dependency matches the name of a workspace package, it resolves to the workspace package (regardless of the requested version). -In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. +In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. Workspace packages do not *necessarily* prevent use of registry packages by the same name - resolution is controlled by the `linkWorkspacePackages` option or `workspace:...` dependencies. From e6da13fb81f0799e3998fd128a25566da11f4f30 Mon Sep 17 00:00:00 2001 From: Dan Rose Date: Fri, 18 Apr 2025 15:03:29 -0500 Subject: [PATCH 3/4] Update pnpm-vs-npm.md --- docs/pnpm-vs-npm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pnpm-vs-npm.md b/docs/pnpm-vs-npm.md index 8ed6a2060d7f..abc7740df8a4 100644 --- a/docs/pnpm-vs-npm.md +++ b/docs/pnpm-vs-npm.md @@ -61,4 +61,4 @@ Npm uses the term "workspace" to refer to the individual packages being co-devel In npm, there is a `package.json` file in the workspace root. The `"workspaces"` field in this file describes where to look for dependencies. Whenever a dependency matches the name of a workspace package, it resolves to the workspace package (regardless of the requested version). -In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. Workspace packages do not *necessarily* prevent use of registry packages by the same name - resolution is controlled by the `linkWorkspacePackages` option or `workspace:...` dependencies. +In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. Workspace packages do not implicitly override registry packages by the same name - resolution is controlled by the `linkWorkspacePackages` option or `workspace:...` dependencies. From 32eae2c3ab9f5dc6f69aae41fa87126be067a9a3 Mon Sep 17 00:00:00 2001 From: Dan Rose Date: Fri, 18 Apr 2025 15:19:12 -0500 Subject: [PATCH 4/4] Update pnpm-vs-npm.md --- docs/pnpm-vs-npm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pnpm-vs-npm.md b/docs/pnpm-vs-npm.md index abc7740df8a4..2ebf757c29d2 100644 --- a/docs/pnpm-vs-npm.md +++ b/docs/pnpm-vs-npm.md @@ -61,4 +61,4 @@ Npm uses the term "workspace" to refer to the individual packages being co-devel In npm, there is a `package.json` file in the workspace root. The `"workspaces"` field in this file describes where to look for dependencies. Whenever a dependency matches the name of a workspace package, it resolves to the workspace package (regardless of the requested version). -In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. Workspace packages do not implicitly override registry packages by the same name - resolution is controlled by the `linkWorkspacePackages` option or `workspace:...` dependencies. +In pnpm, the workspace root contains a `pnpm-workspaces.yaml` file. There may be a `package.json` in the same folder as `pnpm-workspaces.yaml`, but this is regarded as any other package. Workspace packages do not implicitly override registry packages by the same name - resolution depends on the package specifier.