Node

Guide to updating Node engine and npm package versions

Node Engine Version

Node.js has two types of releases: Long-Term Support (LTS) and Current. LTS versions are considered stable and receive updates for an extended period (usually 30 months). Current versions have the latest features but are supported for a shorter duration (around 6 months). All OpenActive projects should be the latest LTS version.

Major version

The major Node version should be updated every 12-18 months to the next even-numbered (LTS) version. This allows for updated version to always have either active or maintenance support.

This upgrade can be substantial, affecting many projects and dependencies, as well being backwards-incompatible with previous versions of Node. There may also be necessary code changes to projects in order to bring them inline with the latest version. For these reasons, this upgrade is done rarely.

Minor and Patch versions

Minor and patch versions are backwards-compatible changes that can introduce new features, bug fixes, and security patches to Node. These updates should be performed regularly to keep the project secure and stable.

Considerations before updating the Node version

Before updating the Node version of a project the following should be considered:

  • Package compatibility: There may be some packages that are not compatible with the newer version of Node. This should be unlikely as only popular and maintained libraries are generally used in OA projects. The following types of libraries should be checked before a Node version upgrade (with an example from an OA project):

    • Bundlers and build tools (for example, babel-eslint is used as the parser for Test Suite's ESLint

    • Node Frameworks (for example express across multiple projects)

    • Testing Frameworks (for example Jest and Chai across multiple projects)

    • Database Drivers (currently not used in Node projects but could be in the future)

    • Authentication and Authorization Libraries (for example openid-client in Test Suite)

    • Front-End Packages (for example puppeteer in Test Suite)

  • Breaking Code Changes: There may be breaking changes that could affect code compatibility between Node versions. For example, between Node 10.x.x and node 12.x.x changes were made to the process object, impacting its methods like process.execPath, process.execArgv, and process.argv[0]. These methods are used in Test Suite and other projects.

  • CI Support: Various projects' CI tools may need to be reconfigured or upgraded to work with the newly upgraded Node version. This could include GitHub Actions which are used across a variety of OA projects for CI workflows.

How to make a Node version update

The following files should be updated when updating the Node version (code snippets provided):

  • .nvmrc (for more information on nvmrc files, see here)

  • package.json

...
  "engines": {
    "node": "X.Y.Z"
  },
...
  • GitHub Actions workflow files

 ...
   - name: Setup Node.js 14.x
    uses: actions/setup-node@v1
    with:
      node-version: 14.x
 ...
  • .vscode/launch.json

...
  "type": "node",
  "runtimeVersion": "18.17.1",
...
  • Dockerfiles: the Docker image may need updating

This is not an exhaustive list, there are likely other files that must also be updated when updating the Node version.

npm Package Versions

Last updated