NodeJS

NodeJS projects using npm can use npm audit to generate a list of vulnerable packages based upon the National Vulnerability Database (NVD). You can subsequently run npm npm audit fix to safely upgrade package versions within the dependency range specified in package.json. The NPM documentation have complete articles on Auditing package dependencies for security vulnerabilities.

This means that a specification of ^1.0.0 in the package.json would update the package-lock.json from 1.0.0 to 1.0.1 but not 2.0.0, this is typically safe as major and patch revisions don’t contain breaking changes. However not all packages adhere to SemVer which can result in errors and deprecated API calls. Testing is advised.

It’s possible to ignore version constraints entirely with npm audit fix --force however this frequently results in broken dependencies. Additionally the there is an Apache-2.0 Licensed external tool called NPM Check Updates which can iteratively install packages to their latest version, regardless of a Major version, executing tests within each update:

npm install -g npm-check-updates
ncu --doctor -u

Two additional parameters --doctorInstall allow you to customise the install command (i.e. npm install vs. yarn install) and --doctorTest allows you to specify the test command, it defaults to npm test. This can be a long-running operation however provides a way to identify breaking changes without installing packages manually with npm install packagename@latest.

Update Run Book

Setup Development Environment

It’s not uncommon for NodeJS project to include hints to the use of the versions of NPM an Node that are recommended for the project, these may either be included in the project.json included as a separate .nvmrc.

The best way to consume these is through the nvm package:

First install nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Re-source your shell:

source ~/.bashrc # for bash
source ~/.zshrc # for zsh

Finally run nvm to install an appropriate version of Node and NPM:

nvm install

Install Hooks

Some projects will have git hooks setup to enforce code style, spelling and commit messages. To configure this it’s important that the prepare scripts referenced in package.json executes, check the output of npm install and the contents of package.json and if required execute the script with:

npm run {{ Insert Setup Script Name Here }}

Update Packages

Before updating packages it’s worth running npm install followed by npm test to ensure that the project builds correctly. If either of those commands you will likely need to inspect package.json to identify the appropriate script to execute with npm run {script name}.

Framework Specific Guidance

Nx

Nx has a concept of automated dependency updates which includes not only updating package.json and package-lock.json but additionally executing code migrations to modify code to account for breaking changes.

The first step is understanding the current version of Nx:

./node_modules/nx/bin/nx.js --version

This version number can be compared to the Nx Changelog to understand if there are multiple major version numbers between the current and latest state.

To upgrade the package.json and update package-json.lock in addition to generating a migrations.json file:

nx migrate latest

To run the migrations:

nx migrate --run-migrations

This will run the migrations, however it will not delete the migrations.json this may be required to upgrade changes in other branches.

At this point you can build and test the project:

npm run build
npm run test

Because Nx test runs are cached, it won’t be necessary to execute them again when committing.

Docusaurus

Older projects may still be on Docusaurus v2, in which case there is specific guidance for upgrading from v2 to v3.

When upgrading between minor versions, it’s essential that each package starting with @docusaurus is upgraded to the target version:

npm install @docusaurus/core@latest @docusaurus/mdx-loader@latest @docusaurus/plugin-google-analytics@latest @docusaurus/plugin-google-gtag@latest @docusaurus/plugin-sitemap@latest @docusaurus/preset-classic@latest

Other packages can be updated using a similar approach. Alternatively npm audit fix can be used.