Hello, while looking through the docs about Sage I noticed what I would call a sub-optimal advice while working with Node.js related dependencies. https://roots.io/sage/docs/installation/
Docs here suggest installing Yarn globally, which I would consider a bad practice. Onboarding other developers or just having multiple projects can be an issue because people running volta install node and npm install --global yarn at different times will produce different results. Someone being onboarded few months into the project can have very different versions of these dependencies.
At the time of writing this post, running volta install node will install Node v20.15.1. and npm install --global yarn will install Yarn v4.3.1
Proposed solution
Instead of suggesting global installs, better solution would be to advise people to pin their Node and Yarn versions locally in the project. This will ensure consistency when using Volta because developers being onboarded onto the project won't need to install anything manually, Volta will just download and use proper version of these dependencies automatically. No mismatch between developer machines.
I would suggest updating docs to something like this:
In your theme directory, make sure to pin your Node.js and Yarn dependencies to a fixed version:
# Pin latest Node.js LTS release locally in the project
$ volta pin node
# Pin latest Yarn release locally in the project
$ volta pin yarn
This ensures all developers working on the project use the same Node.js and Yarn versions automatically when using Volta.
People that for whatever reason need different versions than those specified here can investigate Volta a bit more and can pin custom versions themselves without being instructed how to do so.
Another benefit is that later if Node.js and Yarn dependencies in the project are being updated, it just requires pinning new versions and all people working on the project will automatically get updated to those versions. No manual installation required.
Also, order in the documentation should change because this Node and Yarn step is before theme is even created, so if docs are followed in order, pinning won't work because there is no theme folder yet. This step needs to be performed after the theme is created obviously.
If you think this is a good idea, I can do a PR for this. Wanted to open an issue first instead of just creating a random PR 😄
Summary
Current issue
Hello, while looking through the docs about Sage I noticed what I would call a sub-optimal advice while working with Node.js related dependencies. https://roots.io/sage/docs/installation/
Docs here suggest installing Yarn globally, which I would consider a bad practice. Onboarding other developers or just having multiple projects can be an issue because people running
volta install nodeandnpm install --global yarnat different times will produce different results. Someone being onboarded few months into the project can have very different versions of these dependencies.At the time of writing this post, running
volta install nodewill install Node v20.15.1. andnpm install --global yarnwill install Yarn v4.3.1Proposed solution
Instead of suggesting global installs, better solution would be to advise people to pin their Node and Yarn versions locally in the project. This will ensure consistency when using Volta because developers being onboarded onto the project won't need to install anything manually, Volta will just download and use proper version of these dependencies automatically. No mismatch between developer machines.
I would suggest updating docs to something like this:
In your theme directory, make sure to pin your Node.js and Yarn dependencies to a fixed version:
This ensures all developers working on the project use the same Node.js and Yarn versions automatically when using Volta.
People that for whatever reason need different versions than those specified here can investigate Volta a bit more and can pin custom versions themselves without being instructed how to do so.
Another benefit is that later if Node.js and Yarn dependencies in the project are being updated, it just requires pinning new versions and all people working on the project will automatically get updated to those versions. No manual installation required.
Also, order in the documentation should change because this Node and Yarn step is before theme is even created, so if docs are followed in order, pinning won't work because there is no theme folder yet. This step needs to be performed after the theme is created obviously.
If you think this is a good idea, I can do a PR for this. Wanted to open an issue first instead of just creating a random PR 😄
Additional context
Docs in question
https://roots.io/sage/docs/installation/