Redesign the Downloads page tabs to reflect on latest agreements with Package Maintenance WG

[ovflowd]

The Issue

After the initial redesign of https://nodejs.org, the Downloads page became much cleaner and easier for newcomers and experienced devs to find the method they desired for downloading Node.js.

Although successful, the page structure currently implies a few problems:

• The Package Managers tab mixes Node.js version managers and OS's/App package managers, which also distribute Node.js
• Unofficial and other ways of downloading Node.js are buried within the "Prebuilt Binaries" tab
• No easy way to access a direct link for a Changelog of a given release

• Due to how we recommend Package managers and Node version managers, we cannot add more version managers and other options of package managers maintained by the community.

This issue proposes a UX update that addresses all these problems.

The Solution

Re-arrange/rename tabs and their contents:

I propose a new set of tabs that will respectively contain the following download options:

• Node.js version managers (RECOMMENDED)
• OS package managers
• Prebuilt Binaries
• Other ways

Each one of these tabs will also have a tooltip that renders when users hover said tab headers with the following respective text:

Node.js version managers (RECOMMENDED)

It automatically manages Node.js versions within your system using Node.js-specific version managers such as nvm, fnm, and others.

OS package managers

To install Node.js on your system, use your favorite OS/distribution's built-in or third-party package manager, such as apt, brew, or chocolatey.

Prebuilt Binaries

Download fully self-contained and extractable archives containing binaries of Node.js. Great for portable installations.

Other ways

Find other ways of installing Node.js, such as downloading its source code, unofficial builds, and more.

---

Note that these are just example tooltips prone to being updated and proofread; they should also be translatable.

Move source code and unofficial/other installation methods to "Other ways"

This allows us to easily aggregate the alternative ways of downloading Node.js without obscuring them on the small text below the "Source code" and "Prebuilt Binaries" tabs.

The new Package Manager and Version Manager tabs should be restructured

Within these CodeTabs, you'll be asked for the desired Node.js version, OS, and Architecture (and maybe OS version (?))

The final dropdown box will render options based on these choices, but the main difference is that now we will have options within said Dropdown grouped by "Official" and "Community" options.

The official options are either package managers or version managers sanctioned by the Package Maintenance WG -- and known to always be up to date, regularly maintained, and following best practices. Said best practices and criteria to be defined by @nodejs/package-maintenance; For example, nvm and brew fit this criterion because they follow Node.js versioning standards and LTS standards.

Other options, such as apt, nuget, etc., will be under "Community" options because they aren't always up to date, are based on the OS/distro version, or use different versioning formats.

And then adding a little copy-text on the bottom making the distinction of "Official/Recommended" vs. "Community" -- this distinction is safe enough and the separation for us to allow people to send PRs for adding numerous different package managers and version managers around the clock.

By doing this, we can eventually get rid of the "All package managers" page that is very hard to find.

Changelog Button

When clicked, the changelog button should be an a. It opens the modal (onClick), but all other bindings, like right click and cmd+click, should bind to the default a handlers. People can copy the URLs or open the raw Changelog MD file on GitHub.

---

These are the numerous changes I'm proposing in order to future-proof and make the current Download pages even friendlier and easier to use.

[AugustinMauroy]

I suggest that we change the icon for the links because I don't think the meaning is right. We should put the ‘Link’ icon in place of arrow

[mhdawson]

+1 on the suggestion overall.

[cinderblock]

Glad to see a trackable issue! Thanks! I'd still love to see more mention of WinGet ;)

This, however, raises some extra questions for me...

Why is using a 3rd party "version manager" the "recommended" way? I suspect there have been discussions on this - but where? Personally, I recommend against using anything but the standard OS package install method. The extra headache of having multiple ways to install programs is not worth the gained granularity, imho. If your app needs a specific version of Node to run, it seems easier and more reliable to me to pin it with node as a package.json dependency, but I recognize that the priorities of the Node.js project are a little different than my own...

I'm also surprised to see that OS package managers aren't recommended (or at the same level as binaries/sourcecode). Just because they can be older? It seems to me, as long as the OS (distro) keeps relatively updated versions of Node in their repo, that should be a fully standard way of installing things.

I guess my main thinking is wondering what makes Node Version Managers fundamentally different than a 3rd party package manager? Is it because their package "database"/"backend" is the Node.js website/CDN so they can't be "old"? Why is this a better way of ensuring consistent version numbers than pinning version numbers in package.json#dependencies or package.json#engines?

[ljharb]

OS package managers don't actually provide node, they repackage it and make changes to it and provide that. The largest source of confusion I've seen in the node ecosystem, consistently over the past decade, is apt-installed (or the equivalent) node, and when the user is told to remove it and install it a better way, the problems almost always vanish.

[ovflowd]

I'm also surprised to see that OS package managers aren't recommended (or at the same level as binaries/sourcecode). Just because they can be older? It seems to me, as long as the OS (distro) keeps relatively updated versions of Node in their repo, that should be a fully standard way of installing things.

That's your opinion, and that's fine. However, our priority is providing reliable ways of installing Node that create the least friction, keep the user up to date, and conform to our versioning schemas.

Most OS version managers, as apt, install a Node version based on the distro's release. Then, if you want up-to-date packages, you need to install 3rd-party repositories, like epel or others, depending on the distro.

Note that our end-users, folks downloading Node, are overwhelmingly Developers. Hence, Node version managers are the ideal way of installing Node, as they allow you to have multiple versions and switch Node versions per project.

And yes, there are many other reasons, and no, I apologize, but I won't list them now.

[ovflowd]

I guess my main thinking is wondering what makes Node Version Managers fundamentally different than a 3rd party package manager? Is it because their package "database"/"backend" is the Node.js website/CDN so they can't be "old"? Why is this a better way of ensuring consistent version numbers than pinning version numbers in package.json#dependencies or package.json#engines?

None of the above. If you haven't realized it yet, then that's fine. Maybe @ljharb has more energy to explain the fundamental differences, I'm just a bit mentally drained atm.

[cinderblock]

I think I may have stepped on the wrong foot. I never doubted that people have discussed this at length. I was hoping to get pointed towards that so that I could understand more clearly. Not trying to beat a dead horse; just trying to understand.

I do have some follow up questions based on your responses, but it's clear that this is not the place to continue this conversation.

[ovflowd]

I do have some follow up questions based on your responses, but it's clear that this is not the place to continue this conversation.

I understand where you are coming from; it is more my lack of time and actual mental capacity to provide them to you. Should we have a document that allows newcomers or curious individuals to understand the reasoning better? Yeah, definitely, but all that takes time, and my intent here, although this is a public issue, is to keep track of development already agreed within some WGs and create visibility for the people who are interested in this work, not create an avenue to discuss why we recommend Node.js version managers over OS version managers.

To be clear, the discussion is definitely welcome, but to avoid derailing this issue, I recommend opening a discussion thread/issue on https://github.com/nodejs/package-maintenance.

Apologies for the grumpiness. It is not directed towards you; it is just me being frustrated that I won't be able to provide you with long reasoning and a healthy debacle at the moment due to my own limitations.

[rxmarbles]

Same +1 to the suggestion overall

[ovflowd]

FYI I aim to lead the development on this, but I need to have a final +1 from @nodejs/package-maintenance 🙏

[ovflowd]

Bumping this @nodejs/nodejs-website; unfortunately, I overestimated my availability here. Would anyone volunteer to lead this work? I can sync regarding the overall idea/UX that this should have ✨

[AugustinMauroy]

It reminded me that at the Collab summit @targos had mentioned that on the prebuilt-binairies page it would be interesting to have a codebox with the links for copying and pasting. Because most of the time people who install bianaries do so to use them on a server that they access with SSH.

Michaël could you confirm that was you point of view ?

https://nodejs.org/en/download/prebuilt-binaries

[mhdawson]

A different Michael here, but in terms of using the pre-built binaries my 2 cents is that is what I do all the time. I copy he URL and then use wget to pull down the binary.

[AugustinMauroy]

Can I try to get started on this? If nobody's put their hand in the pudding.

[AugustinMauroy]

[!NOTE] This is a note from the sync we done with Claudio (@ovflowd). So it's the idea of what we are going to do.

• Code Stability Index component
• Button Component size variant
• Remove the Tabs
  • Source Code option will simply cease to exist
  • Remove "Download Node.js the way you want." text
  • Prebuilt Binaries and Prebuilt Installer cease to exist as a tab, but the buttons become part of the "only tab"
  • Code Box will now have a Select Button with "Sections/Groups":
    • Options
      • Official (highlighted and selected by default)
        • nvm
        • docker
      • Commnunity
        • When selecting community option, small banner appears on top (using the Code Stability Index banner, info one)
    • EOL banner to use the Stability Index banner (warning one)
    • Instead of Disabled Options, do not render Version managers that are not compatible with a certain OS due to amount of options
  • Binaries and Installer (when available) becomes two buttons below the codebox (smaller versions)
  • getNodeDownloadSnippet will be deprecated
    • New approach consists of: (https://nodejs.org/en/download/snippets/v22.0.0/nvm) (example)
      • Generator (next-data/generators/getDownloadSnippets)
      • Endpoint: (next-data/download-snippets/route.ts)
      • Provider: (next-data/provides/provideDownloadSnippets)
      • Layout (Provider for MDX Context and retrieve Provider): (layouts/DownloadSnippet.tsx)
        • Uses context from pathname (version is the only required piece on path)
        • Retrieves Release Metadata from the Release Provider and uses current provided Node release
      • Pages: (pages/en/download/snippets)
        • ie: nvm.mdx
        • ie: fnm.mdx ...
      • Route Generation on next.dynamic.constants.mjs, like Blog Page generation DYNAMIC_ROUTES
        • Route Ignores for Download Snippets IGNORED_ROUTES (because these routes cannot be rendered without the context from the path)
      • Iframe embeds the Code Box on the actual Download Page
        • Loading of CodeBox / Empty State as a Skeleton
• Download Buttons for Standalone Binary and Installer (whenever available)
• Create a section within About > Node.js Releases about Officially Supported vs Community Supported (Table with 3 columns)
  • Description | Official | Community
  • Checkboxes
    • Supports releases at the time of Node release (? better wording)
    • Does not modify Node binaries / changes what gets distributed
    • Maintainers have direct communication with Node maintainers
    • ... to be defined full list of comparison
• Remove the All Package Managers reference link
• Remove Unofficial and Nightly from the Download page
  • Move to the About > Node.js Releases, as links on the table of Major Releases (as link to latest maybe)
  • Add N-API version also on the table

Mock up

[masterflitzer]

seems a bit backwards to suggest installing fnm via winget but not to mention that one can also just install nodejs via winget directly

also docker being the only "official" method on windows is just bad, it paints a picture of nodejs not wanting to officially support windows

[ovflowd]

seems a bit backwards to suggest installing fnm via winget but not to mention that one can also just install nodejs via winget directly

also docker being the only "official" method on windows is just bad, it paints a picture of nodejs not wanting to officially support windows

I would appreciate not jumping to conclusions. This PR was a first pass. We will eventually add fnm as an official method.

We unfortunately cannot add Winget as an installation method because it is barely updated, the latest version added there is 19.8.1 which is extremely old. There doesn't seem to be any of the v20,v21,v22 and v23 versions there as per https://winget.run/pkg/OpenJS/NodeJS

[ovflowd]

Also per statistics most of Windows users still download and install Node.js via the Windows installer, or at least based on metrics from Sentry.

There are follow-ups to this PR which is an initial pass.

[masterflitzer]

winget is pretty up to date as far as i can see (winget.run, winstall.app or any similar sites are not official, so not really a reliable source):

• openjs.nodejs is on 23.5.0: https://github.com/microsoft/winget-pkgs/tree/master/manifests/o/OpenJS/NodeJS
• openjs.nodejs.lts is at 22.12.0: https://github.com/microsoft/winget-pkgs/tree/master/manifests/o/OpenJS/NodeJS/LTS

anyway i apologize for jumping to conclusions, i just wanted to bring attention to it as imo it currently seems half baked, i wasn't aware that it's only a first iteration, so all good i appreciate y'all tackling this

[ovflowd]

winget is pretty up to date as far as i can see (winget.run, winstall.app or any similar sites are not official, so not really a reliable source):

Oh I had no idea, I stand corrected.

anyway i apologize for jumping to conclusions, i just wanted to bring attention to it as imo it currently seems half baked, i wasn't aware that it's only a first iteration, so all good i appreciate y'all tackling this

No worries! Appreciate you bringing this up to our attention. We wanted to merge this soon so we could then iterate and allow the community to start adding new methods.

I definitely agree that Docker appearing as the default method feels, uhm, yeah.