feat: Add nvm migration guide #104
Conversation
brendaneamon
requested review from
rossturk,
jennymahmoudi,
zmitchell and
barstoolbluz
docs/tutorials/migrations/nvm.md
Outdated
|
|
||
| Flox is an environment and package manager that allows you install software from an extensive catalog into individual [environments][environment_concept]{:target="\_blank"}, each of which usually corresponds to a software project. Flox gives you the opportunity to simplify the development workflow used by your team, consolidating various functions into a single command: `flox activate`. | ||
|
|
||
| Just like [nvm](https://github.com/nvm-sh/nvm){:target="\_blank"}, Flox allows you to install and activate different versions of Node.js, allowing developers to switch versions as project requirements dictate. |
There was a problem hiding this comment.
May want to clarify that it's not a only an nvm alternative. I only say that because we've gotten feedback that it's not immediately obvious that it works across different languages.
docs/tutorials/migrations/nvm.md
Outdated
| ## Why you might want to use Flox instead of nvm | ||
| nvm does exactly what it purports to do: it manages Node.js versions simply and effectively. Point notwithstanding, it's also one more dependency that you don't have to worry about if you're using Flox. Consider whether one of the following cases applies to you, or to your team: | ||
|
|
||
| * **You work with other engineers who are not JavaScript developers.** Flox will allow your team members who are not TypeScript or JavaScript developers to get up and running on your project, with the correct Node.js version. They won't have to install and use an unfamiliar toolchain in a language with which they might not be familiar. Instead, they can use well known Flox commands to activate their dev environments. |
There was a problem hiding this comment.
Instead, they can use well known Flox commands to activate their dev environments.
I think it's more convincing to frame this as having one entry point regardless of the language ecosystem. If I'm not a JS developer, and I don't already use Flox, I don't know that I gain much by trading one unfamiliar set of commands for another. If Flox is a single entry point for any language ecosystem, it becomes more attractive to migrate to it.
There was a problem hiding this comment.
I think what you said is what I was trying to capture, but I can see that I need to add some clarity and reword some of this. As written, I can see that Flox being a single entry point for any language ecosystem is a bit lost.
docs/tutorials/migrations/nvm.md
Outdated
|
|
||
| Flox is an environment and package manager that allows you install software from an extensive catalog into individual [environments][environment_concept]{:target="\_blank"}, each of which usually corresponds to a software project. Flox gives you the opportunity to simplify the development workflow used by your team, consolidating various functions into a single command: `flox activate`. | ||
|
|
||
| Just like [nvm](https://github.com/nvm-sh/nvm){:target="\_blank"}, Flox allows you to install and activate different versions of Node.js, allowing developers to switch versions as project requirements dictate. |
There was a problem hiding this comment.
What's with the {:target="\_blank"}?
There was a problem hiding this comment.
It is a good practice to open a new tab / window when linking offsite, I like this! Perhaps mkdocs can automate.
There was a problem hiding this comment.
Yeah, I would for sure open all external links in a new tab. My personal preference is also to open other Flox docs links in new tabs, but I can drop that if it's non-standard and potentially confusing to the user.
docs/tutorials/migrations/nvm.md
Outdated
| v22.10.0 | ||
| ``` | ||
|
|
||
| If you'd like more granular control over the Node.js version to install, you can get the correct Flox catalog version name for the desired Node.js version by running `flox show <package>`: |
There was a problem hiding this comment.
I think this section belongs before the upgrade to v22, otherwise it seems like the upgrade process is "uninstall, then install the different version" as opposed to flox upgrade. Then you can frame the upgrade to v22 as "suppose you want a specific version".
There was a problem hiding this comment.
I was having a little bit of trouble with a straight upgrade here, and I think that's perhaps a quirk of how node versions end up in nixpkgs. I'll try a few things tomorrow to see if I can work out the kinks with the upgrade. The main issue is that node versions higher than 20 don't see to be included if you try to flox install nodejs as opposed to flox install nodejs_22. I wonder if that's still an "upgrade" if those are different packages in the catalog.
docs/tutorials/migrations/nvm.md
Outdated
|
|
||
| # Node Version Manager (nvm) migration guide | ||
|
|
||
| Flox is an environment and package manager that allows you install software from an extensive catalog into individual [environments][environment_concept]{:target="\_blank"}, each of which usually corresponds to a software project. Flox gives you the opportunity to simplify the development workflow used by your team, consolidating various functions into a single command: `flox activate`. |
There was a problem hiding this comment.
typo: allows you to install
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
edb1941 to
6b85873
Compare
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
6b85873 to
a2532ee
Compare
docs/tutorials/migrations/nvm.md
Outdated
| nvm does exactly what it purports to do: it manages Node.js versions simply and effectively. Point notwithstanding, it's also one more dependency that you don't have to worry about if you're using Flox. Consider whether one of the following cases applies to you, or to your team: | ||
|
|
||
| * **You work on a team with members who have diverse skill sets, and you want to have a single entrypoint for development, regardless of language ecosystem.** No matter what languages and technologies your team is comfortable with, they can use the same Flox commands to spin up their local dev environments. For example, instead of forcing a Java developer with a Linux machine to install nvm to work on your project, you can offer a better solution. That developer can use the same Flox commands they use to activate their own projects to activate the dev environment for your node project, which you develop on your Mac. | ||
| * **You want a tool that allows you to manage Node.js versions as well as other dependencies.** Having a single-use tool like nvm is fine, but what if you could install node, PostgreSQL, nginx, etc. with a single command? Flox let's you do just that, and it also [allows you to configure and run services][services]{:target="\_blank"} like PostgreSQL simply by adding the `--start-services` argument to `flox activate`. |
There was a problem hiding this comment.
| * **You want a tool that allows you to manage Node.js versions as well as other dependencies.** Having a single-use tool like nvm is fine, but what if you could install node, PostgreSQL, nginx, etc. with a single command? Flox let's you do just that, and it also [allows you to configure and run services][services]{:target="\_blank"} like PostgreSQL simply by adding the `--start-services` argument to `flox activate`. | |
| * **You want a tool that allows you to manage Node.js versions as well as other dependencies.** Having a single-use tool like nvm is fine, but what if you could install node, PostgreSQL, nginx, etc. with a single command? Flox lets you do just that, and it also [allows you to configure and run services][services]{:target="\_blank"} like PostgreSQL simply by adding the `--start-services` argument to `flox activate`. |
There was a problem hiding this comment.
🤦🏻
Thank you for catching that 🙏🏻
|
|
||
| ## Create a Flox environment in your existing project and install Node.js | ||
| Navigate to your project's directory and run `flox init`, and then search for the version of Node.js that is currently included in your `.nvmrc`, or in the `"engines"` property of your `package.json`. (Note that node is listed as `nodejs` and variants thereof in the Flox catalog.) | ||
|
|
There was a problem hiding this comment.
Did you decide not to mention the auto-setup for node? or did it not work?
There was a problem hiding this comment.
Sadly, the automatic setup doesn't work, because of how the node versions are listed in the catalog. Zach has captured this issue in a ticket: flox/flox#2507
| ```zsh | ||
| ➜ node-project git:(main) ✗ flox install nodejs_22 | ||
| ✅ 'nodejs' installed to environment 'node-project' | ||
| ``` |
There was a problem hiding this comment.
Any reason why this wouldn't say 'nodejs_22' installed to environment instead of nodejs?
There was a problem hiding this comment.
Upon some reflection and discussion, I think we should advocate for users to install specific versions of node rather than the generic nodejs package, which to me seems like an alias for "latest" or something to that effect.
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
a2532ee to
5d5c8f1
Compare
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
5d5c8f1 to
acee6a3
Compare
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
acee6a3 to
5e2381d
Compare
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
5e2381d to
313d899
Compare
brendaneamon
force-pushed
the
brendan/add-nvm-migration-guide
branch
from
313d899 to
db1d0c5
Compare
Notes for reviewers
flox activate -d ~/node-versions/20as it is to runnvm use 20, given the added overhead of creating the Flox environment manually for each node version that you might want to use. My view is that the guide handles the most common use cases, but do correct me if you disagree!uninstalland theninstall.