[RFC] How should contributors manage node versions in local environments?

[johnhunter]

Summary

Contributors are advised to use Node 16 when developing locally. There are various Node version managers available and Storybook has not prescribed a specific tool or approach. I recently raised a PR #23709 to use Volta https://volta.sh/ but configuring it to work correctly with large monorepos isn't ideal as each package.json needs an additional field. I'm considering reversing the changes in that PR but also think some form of node version management might be helpful for contributor onboarding.

Problem Statement

• We expect contributors to use a specific node version but do not enforce it.
• Managing node versions with configuration, along with recommended tooling, would reduce barriers for new contributors.
• I added config and notes on using Volta for version management in #23708 Add volta pin settings and duplicate packageManager setting #23709 but have discovered it requires settings per package.json to maintain a consistent node version across all packages.

Non-goals

• Should we support a wider range of node versions and increase CI test matrices to cover.

Implementation

I propose we recommend a node version manager tool to contributors and include the configuration to ensure the specified version is used in development. This configuration should be in sync with the CI test, build and publish tasks.

My original proposal was to use Volta as I have used it successfully on other projects. However, I'm not sure it is the right solution for Storybook and am therefore calling for alternative proposals.

Volta is installed locally and shims node, automatically installing a specific node (and yarn) version based on configuration within the project's package.json file. e.g:

  "volta": {
    "node": "16.20.1",
    "yarn": "3.5.1"
  }

However, Volta treats each project (i.e. a folder containing an package.json file) as a separate entity and if it does not find a "volta" setting for that package it uses the user's default. Currently Volta addresses this by using an extends to reference an ancestor package, e.g:

  "volta": {
    "extends": "../package.json"
  }

In the Storybook monorepo we have a lot of package.json files. There are currently 100 that contain a scripts object and therefore potentially run node scripts. We could update all the packages to reference the root package.json file giving us a single source for configuration. But it is a lot of change for specific tooling and I'm not Volta is something that everyone will want to use.

There is a long running issue on the Volta github about this approach to configuration volta-cli/volta#282 and they do not appear to have reached any consensus.

Prior Art

There are other node package managers out there, Volta is a relative newcomer.

NVM uses a configuration file .nvmrc that may be better suited to Storybook.
There may be other alternatives we could propose?

Deliverables

1. Evaluate options for node package managers
2. Implement configuration for managing node version
3. Update contributor 'getting started' documentation along with any migration for existing contributors.
4. Update maintainers documentation for node version bumping

Risks

• Contributors may already have node version management that works well for them, ideally they should continue to work
• New contributors are trading off additional setup against a consistent and predictable environment.

Unresolved Questions

• Can we have consensus on the right node version management solution for the whole community?
• Is the solution overly coupled to a single tool?
• Is the selected tool stable and well supported?

Alternatives considered / Abandoned Ideas

I've proposed Volta as a personal preference but I'm not sure its right for Storybook. I'm keen to hear alternatives.

[yannbf]

Hey @johnhunter, thank you so much for writing this nicely detailed RFC! We agree that it would bring much more value to the contributors if we had a solution for this. Seems like volta is not the best fit, and that we should use a solution that supports the .nvmrc file. NVM sounds good, seems like collaborators that use other tools like FNM and others would still benefit from this configuration as well. Is this something you'd be interested in working on?

Unresolved questions:

Can we have consensus on the right node version management solution for the whole community?

Anything that supports .nvmrc.

Is the solution overly coupled to a single tool?

Seems like volta would, but .nvmrc is a standard supported by many tools.

Is the selected tool stable and well supported?

NVM is!

Additional tasks:
It would be great to also configure CI environments to also point to the .nvmrc file, instead of us having to manually define versions (apart from the matrices, and the publish script which we will need to be on node 18.)

For the node version, we need to keep using 16.x until we drop support for it.

Thanks once again! Looking forward to hearing back from you.

[johnhunter]

Thanks for your feedback @yannbf I'm happy to take this on. I might need to reach out on the CI configuration but will see how it goes. I should be able to put some time on it this week.

[johnhunter]

PR raised #24015

Driving the Node version from config in CI is challenging for the CircleCI workflows as it uses cimg images with specific node versions. It might be possible to use configuration with Dynamic configs although there is no guarantee of a 1:1 mapping of Node versions to CircleCI cimgs.

[johnhunter]

PR merged