Node.js runtime upgrade to version 22

Neptune DXP - Open Edition is upgrading its runtime environment from Node.js 18 to Node.js 22. This update is necessary because Node.js 18 has reached end-of-life and will no longer receive security patches or maintenance updates.

Node.js 22 introduces several technical changes that may affect application behavior. See the official release announcement from The Node.js Proejct here.

Scope of Impact

Most actively maintained npm packages that follow semantic versioning (semver) are expected to work without modification. However, applications may require changes or testing if they involve:

  • Custom or internally maintained npm modules

  • Native bindings

  • Deprecated or removed Node.js APIs

Migration Checklist

Follow these steps to prepare your development and deployment environments for Node.js 22:

  1. Upgrade your local Node.js version to 22.13.1 or later.

    You can check if your local Node.js version, used when installing npm modules, matches at least the minor embedded Node.js version of the Neptune DXP - Open Edition runtime system on the System Info tile of the Cockpit.

  2. Test your application in a Node.js 22 environment, focusing on modules that are not officially supported or are custom-built.

  3. Identify outdated dependencies using:

    npm outdated
npm-check-updates

  4. Update outdated packages, prioritizing those with native components or known compatibility constraints.

  5. Rebuild native modules:

    npm rebuild

  6. Monitor for warnings or errors:

    • Check for deprecation warning messages during application startup

    • Review logs for runtime errors that did not occur under Node.js v18

  7. If your application uses custom npm modules, you can rebuild and validate these in their installation path found in Custom Settings → General → npm Installation Path.