We’re switching Discourse core’s JS package manager from from ‘yarn classic’ to pnpm. This will bring significant improvements to install speed & storage requirements.
Production
If you use managed hosting or a standard install, then you don’t need to do anything. The change will be applied automatically on your next update.
If you have a custom production environment, you’ll need to change any yarn ... commands to pnpm ...
Development
After pulling the latest version of Discourse core, you may see an error like this when starting the server:
pnpm is not installed
or, if you run a command like yarn install, you will see
error discourse@: The engine "yarn" is incompatible with this module. Expected version "please-use-pnpm". Got "..."
To resolve this, you should:
run npm install -g pnpm
run pnpm install
replace any uses of yarn ... in your development environment with pnpm ...
Plugins / Themes
For now, our official plugins/themes continue to use yarn for their linting dependencies. We’ll be updating them over the coming weeks.
Switching back to yarn
If you need to switch back to a yarn-based version of Discourse (e.g. developing on the stable branch), then you’ll need to manually delete all of core’s node_modules directories:
I am contributing to another FOSS project where I was recently introduced for the first time to PNPM. The transition was a complete no-brainer, smooth, effective, and a real pleasure.
I wrote up very brief notes in the documentation for that project for What PNPM Is, and how to use it. While the tiny details are different for every project, I hope what’s there might provide a quick intro to anyone here, who like me didn’t have a clue before an announcement was made.
It’s worth noting though - none of the “configuration notes” there are required for Discourse. Not sure why they need it… maybe because it’s a windows-based application?
Also, their note about “In an existing project, just delete the ‘node_modules’ folder” is handled automatically in Discourse by this script
Thanks for your contribution to FOSS docs @david It does look like the page is oriented toward Windows, and that the info there might be required knowledge for using pnpm. I will edit and clarify that neither is the case for that utility.
To be clear, the info about how pnpm works is only there for the comfort of the user/developer, including those here who might like to understand this new tool that replaces a significant, often used tool in our kit.
For Discourse devs, that info explains where things are located and how to change default locations. This is intended to answer a question like “if all of my node_modules are now in one location, where are they?” In the Discourse container, you devs might not want packages in the default location. If, for whatever reason, a plugin developer is directly referencing the node_modules folder and they find links to another location rather than files, the info on that page concisely explains how that location is determined.
With our standard plugin skeleton, each plugin has its own package.json file with its linting dependencies. And for now, the skeleton still uses yarn.
So to lint a specific plugin, you would go into the plugin directory and run
yarn install
yarn prettier --write
Using core’s linting config on plugins can work sometimes. But if the version/config diverges, it can get painful because the version of eslint/prettier in core won’t match the version running in your plugin’s CI.
This seems to have worked correctly, but was confused by notice that seems to state this needs to be done manually and is not automatic for standard install site:
Ran into an issue upgrading via the web tool — the upgrade page said the upgrade failed, with the Expected version "please-use-pnpm" error, but when I subsequently visited the Versions page again it appeared that the upgrade succeeded:
Maybe it’s our Communiteq environment, but TBH I don’t see any significant speed improvements during installation? Our stable test install even installs 23 seconds quicker than the tests-passed one.
It does look like the page is oriented toward Windows, and that the info there might be required knowledge for using pnpm. I will edit and clarify that neither is the case for that utility.
)
