RFC: node versions of Nextcloud libraries

[susnux]

Summary of proposed changes

• Use devEngines for libraries similar to engines of apps
• Libraries engines contain active + maintenance LTS Node version but no NPM dependency.

RFC

With RFC-5¹ we standardized the node environment for apps, and currently we apply the same rules also for libraries.
But for libraries there is a different need, because apps depend on libraries and apps can support old Nextcloud version.

Problem: Stable branches

Apps have stable branches or support a long range of Nextcloud versions and as soon as we branch off apps we do not update their Node dependencies for good reasons.

Installing the library on that stable branch will warn about a too new version of Node now even if the library is intended to also work for old Nextcloud versions in stable branch apps.

No latest version available

A related problem is that npm with version 11 will not announce new package versions if the engines do not match.
Lets say you have a stable branch of app A which uses the library L. A will not update its node dependencies as it is a stable branch, but L will as it is the latest version.
If there is a bugfix in L it will not be announced to A because the engines mismatch.

Problem: Not a node library

Another problem: Our libraries (except from the *-config ones) are not Node.js libraries but intended to be used in the browser.
So currently we state Node and NPM as a dependency (engines) of that library even if they are no dependencies.
But for libraries NPM is not a dependency because we only ship the package.json which is universal and also works with pnpm or yarn - and Node is not a dependency as we target the browser, so since Node 18 we are universal as we switched to ESM.

Proposed changes

For apps RFC-5¹ should stay as it is.

For libraries:

1. We change the engines.node version to active LTS + previous maintenance LTS
   • This way we support current Nextcloud and all supported versions (1 year = ~3 Nextcloud versions)
2. We drop the engines.npm requirement entirely as this is not a runtime dependency of libraries
3. To enforce standard tooling we instead add devEngines to package.json - this allows to have consistent developer environment.

Clarifications:

• active LTS: version used for current apps¹ (at the time of writing Node 22)
• previous LTS: at least the latest LTS in maintenance support (which is active LTS - 2) (as of writing: Node 20)
• Libraries should be free to also offer support for current LTS which is the latest even node version (as of writing Node 24)
• Libraries should never offer support for unstable Node versions (uneven version number such as Node 23).
• devEngines define the engines to use for development, so we want to enforce NPM + Node for consistency
  • The versions should be aligned with the app versions¹ to make development within the Nextcloud ecosystem easier.

Example changes:

engines of a library:

    "engines": {
        "node": "^22 || ^20",
    },

with current support:

    "engines": {
        "node": "^24 || ^22 || ^20",
    },

devEngines:

{
  "devEngines": {
    "runtime": {
      "name": "node",
      "version": "^22",
      "onFail": "error"
    },
    "packageManager": {
      "name": "npm",
     "version": "^10",
      "onFail": "error"
    }
  }
}

---

Footnotes

1. https://github.com/nextcloud/standards/issues/5 ↩ ↩² ↩³ ↩⁴

[ShGKme]

I've never heard about devEngines before 😮

Everything sounds great, I agree with every point.

[susnux]

I've never heard about devEngines before 😮

Probably because it was introduced with NPM 10 😉

[susnux]

Would also ping @juliusknorr and @ChristophWurst as their teams are maybe affected