Skip to content

Runtime Support

Nuzo requires:

  • Node.js 22 or newer;
  • npm 10 or newer.

The supported and continuously tested Node.js lines for the MVP are:

Runtime Support
Node.js 22 LTS Supported and tested in CI.
Node.js 24 LTS Supported and tested in CI.
Older than Node.js 22 Unsupported.
Other Node.js major versions Not claimed as supported until added to CI.

The engines fields express the minimum runtime requirement. They do not replace the tested-version policy above. A newer or non-LTS major may satisfy >=22 without being part of the supported CI matrix.

Native SQLite Dependency

Nuzo uses better-sqlite3, which includes a native Node.js module.

On common supported platforms, npm should download a prebuilt binary. If no compatible prebuild is available, installation falls back to compiling the module locally.

Use a supported LTS release before troubleshooting:

node --version
npm --version
npm ci

If compilation is required, install the platform toolchain:

sudo apt-get update
sudo apt-get install -y build-essential python3
npm ci

xcode-select --install
npm ci

Install Python and Visual Studio Build Tools with the Desktop development with C++ workload, then run:

npm ci

If installation still fails:

  1. Confirm the active Node.js version is 22 LTS or 24 LTS.
  2. Remove node_modules without deleting package-lock.json.
  3. Run npm cache verify.
  4. Run npm ci again and inspect the first native build error.

Do not regenerate or discard the lockfile as a generic troubleshooting step.

Changing The Policy

A runtime support change must update together:

  • root and workspace package.json engine declarations;
  • the Node.js matrix in .github/workflows/ci.yml;
  • clean install and release documentation;
  • CHANGELOG.md when the change affects users.

Dropping a supported Node.js line after the first public release is a breaking change.