[BUG] Workspaces are not documented, don't appear to work

[justinfagnani]

• This blog post says that npm 7 comes with a new feature called workspaces: https://github.blog/2020-10-13-presenting-v7-0-0-of-the-npm-cli/
• The blog post only links to this RFC: https://github.com/npm/rfcs/blob/latest/implemented/0026-workspaces.md
• The behavior of workspaces does not match the RFC (ie, no symlinks are created)
• There are no mentions of workspaces in the current or new docs
• Fundamental functionality of workspaces, like installing dependencies, does not work: [BUG] Can't install new dependencies into workspace package with workspace dependencies #2035 and [BUG] package-lock.json not updated with new dependencies of a workspace package #1984

What is the status of workspaces? Have they actually launched with npm 7? And should anyone actually be trying them yet?

I feel like if the feature really launched that it would be documented somewhere besides an RFC. They're mentioned in the release post, but essentially no where else. I'm very confused about whether we should be able to use them or not.

Could something about their status be added to the public docs?

[ruyadorno]

hi @justinfagnani thanks for the feedback 😊 Let me try my best to clarify a few things:

There are no mentions of workspaces in the current or new docs

It's there in the documentation bundled with npm v7, to read it you can run:

• npm help workspaces Open manual page in the terminal
• npm help workspaces --viewer=browser Opens the same doc page in a browser instead

Fundamental functionality of workspaces, like installing dependencies, does not work: #2035 and #1984

While we strive to build perfect software, there are sometimes unintended bugs and/or adjustments to be made and we'll continue to tackle those in our weekly patch releases.

What is the status of workspaces? Have they actually launched with npm 7? And should anyone actually be trying them yet?

The workspaces support shipped with npm@7.0.x is the foundation work that gets workspaces properly linked in the context of a npm install from the top-level root package. The intent when we chose to attach the RFC link itself to the blog post and other communication channels was to be transparent and make it very clear from a technical point of view what level of support is being provided.

Personally, one of my main design goals while implementing the workspaces support was to make sure it is still extensible and catering the rich ecosystem of existing tooling - that said, if you need a more feature-rich experience in npm@7.0.x you might want to use it along other tools such as lerna that will provide a wide range of workflows around managing workspaces while benefiting from npm7 being able to properly install them. Lerna in particular has a useWorkspaces configuration to lerna bootstrap that should enable just that.

We do have a follow-up RFC that extends the set of features provided out of the box by the npm cli and you can keep an eye for that landing in a future semver-minor release of v7.

Could something about their status be added to the public docs?

As I mentioned before they are a part of the public docs shipped within the npm cli but I also understand you might be referring to the https://docs.npmjs.com/ website. In that case we have a team that is hard at work to getting it up-to-date soon.

Alright, I'm sorry the reply got this long but I feel it was worth the extra details 😊 I really appreciate your input as it's a very valuable external feedback that will help us shape the communications moving forward - for one, I do have speaking engagements and more blog posting lined up and I'll make sure to translate better what the description in the RFC really means in plain text.

Thanks again and please let me know if there are still any questions! 😄

[protyposis]

Hi @ruyadorno, thank for the helpful clarification. Could you please also elaborate on the following workspace-related questions:

• Is there supposed to be one single package-lock.json at the workspaces root (like Yarn 1 does), or can/should there be individual lockfiles in workspace packages (like Lerna creates them)?
• How are we supposed to install/uninstall packages within a workspace? It seems these commands cannot resolve local dependencies linked within the workspace root node_packages folder.
  • Example: workspace package @myworkspace/package-b depends on workspace package @myworkspace/package-a. I am getting npm ERR! code ETARGET / npm ERR! notarget No matching version found for @myworkspace/package-a@^1.0.0 errors in package-b unless I change the package reference to a local path reference ("@myworkspace/package-a": "file:../package-a"). Are we supposed to use such local path references (which then requires 3rd party tools like Lerna that transform the package.json to semver notation deps on publish)? The original workspaces RFC suggests otherwise.
  • You are saying that we "might want to use [npm@7.0] along other tools such as lerna that will provide a wide range of workflows around managing workspaces". Lerna has an add command that installs dependencies into workspace packages which also works with package.json files containing local semver dependency expressions - there is however no native command to uninstall a package (Feature: lerna remove lerna/lerna#1886, WIP: feat(remove): initial commit for lerna remove lerna/lerna#1887 (comment)), so I need to use npm uninstall which loops back to the described issue.

[ruyadorno]

• Is there supposed to be one single package-lock.json at the workspaces root (like Yarn 1 does), or can/should there be individual lockfiles in workspace packages (like Lerna creates them)?

Yep, there should be just one single package-lock.json 👍

• How are we supposed to install/uninstall packages within a workspace? It seems these commands cannot resolve local dependencies linked within the workspace root node_packages folder.

For npm@7.0.x alone the best way to handle them is manually editing the package.json for each child workspace and run npm install from the top-level 😊

• Example: workspace package @myworkspace/package-b depends on workspace package @myworkspace/package-a. I am getting npm ERR! code ETARGET / npm ERR! notarget No matching version found for @myworkspace/package-a@^1.0.0 errors in package-b unless I change the package reference to a local path reference ("@myworkspace/package-a": "file:../package-a"). Are we supposed to use such local path references (which then requires 3rd party tools like Lerna that transform the package.json to semver notation deps on publish)? The original workspaces RFC suggests otherwise.

hmmm 🤔 might be a legit bug - from your specific example it would be nice to validate that both @myworkspace/package-b and @myworkspace/package-a are properly defined/discoverable from your package.json "workspaces" property (all workspaces need to be defined there, even the ones which are dependencies of a nested workspace). The goal for workspaces is not having to use the file:./<location> as semver range as you mentioned, so that's def not the case. 😊

• You are saying that we "might want to use [npm@7.0] along other tools such as lerna that will provide a wide range of workflows around managing workspaces". Lerna has an add command that installs dependencies into workspace packages which also works with package.json files containing local semver dependency expressions - there is however no native command to uninstall a package (Feature: lerna remove lerna/lerna#1886, WIP: feat(remove): initial commit for lerna remove lerna/lerna#1887 (comment)), so I need to use npm uninstall which loops back to the described issue.

Same as for adding a new dep, the vanilla workflow for now is to manually edit the package.json file of a nested workspace in order to to remove the dependency you want to uninstall and then run npm install from the top-level folder, as I also mentioned in the previous reply that should be changing within the upcoming minor versions in which we'll get to tackle the workspaces workflows as described in the current open RFC.

[justinfagnani]

Thanks for the response @ruyadorno. I didn't mean to imply that I think npm should make perfect software. I just really could tell what the status of the feature was given its absence from the docs site, and my inability to get it working beyond the initial install. I'll check out npm help and look forward to the 7.x docs on the website. I'll follow up on specific issues for functionality.

[ruyadorno]

btw new docs are up 😍 https://docs.npmjs.com/cli/v7/using-npm/workspaces - thanks @ethomson ❤️

[andrew-hm]

Any plans to support "nohoist"? Required for react-native work

[ruyadorno]

hi @acates-happymoney I think it might be better to track that in a separate issue, would be awesome if you could provide a reproduction case so that it's easier for us to know better how to act on it 😊

[andrew-hm]

Using yarn as an example to contrast against in regard to  noHoist. Using the workspaces feature, yarn does not add dependencies to node_modules directories in your packages  –  only at the root level, i.e., yarn hoists all dependencies to the root level. yarn leverages symlinks to point to the different packages. Thereby, yarn includes the dependencies only once in the project. Note, this is on par with npm now.

You have to utilize yarn workspaces’ noHoist feature to use otherwise incompatible 3rd party dependencies working in the monorepo environment. You have to specify this in the project root package.json. For more information take a look at the demo project of ConnectDotz.

In either event, thanks in advance for the quick response. It sounds like it wont be anytime soon so that was the answer I was looking for!! Cheers and great work on npm7.