Info: Troubleshooting Node Errors and Versions with NVM and NPM

[daveseah]

Stub for capturing information about it.

We use NVM to set the version of NodeJS in a project. We specify a specific version of NodeJS in the .nvmrc file inside the project root, but it generally has to be manually set with the nvm use command BEFORE running any npm commands.

• what version of node is specified? cat .nvmrc
• what does nvm think is the current active version of node? nvm which
• what is the actual command line version of node? node -v

The one that matters is what is reported by node -v

When nvm use switches the version of node, it does this by changing the global path to the node binary. However, it does not change the modules loaded in node_modules, so it's good to remove that folder and do npm ci again.

Gotchya: there is also a global node_modules cache from which modules are reinstalled without redownloading them from the internet. This is supposed to work invisibly but in some cases (e.g. poorly versioned libraries) problems with compilation will occur.

When "it runs on my machine" but not others, some sources of problems are:

• not using nvm use to set the version if you were working on another problem, especially if you have set a default alias through nvm alias default v14.21.3 or something.
• not checking that nvm use has actually changed the node version by comparing cat .nvmrc with node -v
• not running npm run bootstrap after changing any library dependencies
• using an old version of node that isn't supported on Apple Silicon
• not changing node versions to the supported one before using npm ci
• using npm install when you should use npm ci which preserves the exact dependency order.
• accidentally using npm install and trying to restore from npm ci without doing a complete restore of package-lock.json from the repo (using npm install destroyed it)
• dev environment is very old and cached modules in the global npm cache that have the same version number actually have changed, so other systems are pulling a different module. The global npm cache persists even if you run npm ci again so you may need to manually purge it with the npm cache clean --force command. Note: this will make installs very slow again the first time
• a developer added a new package dependency but didn't add the change in package.json or commit package-lock.json, so this breaks the repo for others

There are minimum versions of node to use:

• For use of exports over main in package.json, v12.7
• To use ES modules, v15.3 and above is required. This introduces very stringent file extension rules and is not a light undertaking.
• Apple Silicon (M1, etc) full support in v16 and above. If using versions before v16, the shell must be forced to use intel emulation through Rosetta with arch -x86_64 $0 and then reinstalling node_modules with npm ci or in some cases npm install (conditions still TBD)

[dsriseah]

This issue should be closed by #795