May 20, 2022

Plugin Compatibility and Semantic Versioning (semver)

Graffitti art of a puzzle consisting of many multi-coloured pieces

Over the years, NodeBB has amassed quite a collection of plugins, most of which were published to npm and listed in the “Manage Plugins” page in the admin control panel.

With the release of v2.0.0, we received some reports that the plugin directory was now empty.

This was intentionally done, for a number of reasons—read on!

Changes to Plugin Compatibility

Plugins are encouraged to maintain a property in their package.json called nbbpm. Contained inside this property is a field called compatibility, which is a semantic versioning range of NodeBB versions that the plugin is supposed to be compatible with1.

For example, a plugin may have the following in their config.json:

  "nbbpm": {
    "compatibility": "^1.17.0"

This directive instructs the NodeBB Package Manager (nbbpm) that the plugin is compatible with NodeBB v1.17.0 and up.

The unofficial standard was to use the carat symbol in the range, which—for the above example—meant that the plugin is compatible with NodeBB versions v1.17.0 through to v2.0.0 (not inclusive of v2.0.0).

It’s because of that exclusivity that meant that all existing plugins (or at least those that reported their compatibility) were no longer listed in v2.0.0.

If you maintain a plugin and would like to see your plugin in the list again:

  1. Run through the migration guide—make sure your plugin is actually compatible!
  2. Append || ^2.0.0 your compatibility string

Adoption of Semver

In the v1.x releases of NodeBB, we did not strictly follow Semantic Versioning.

We would wilfully include breaking changes in minor releases, and patch releases could contain new and backwards-compatible features. Major releases were not done regularly, because we felt that the incrementing of the major version number signified that something big had changed.

We ended up doing just that with the release of version 2—webpack changes caused a great number of plugins to need adjustment.

However, in the end, a number is just a number, and given the semver ranges in compatibility, it makes sense to adopt semantic versioning for NodeBB core as well.

Going forward, the NodeBB release behaviour will be as follows—

  • Patch releases
    • will not be constrained to a specific day, and can occur at any time
    • will occur much more frequently than before
    • will contain only bug fixes
    • will contain fewer (if any) upgrade side-effects
  • Minor releases
    • will continue to be restricted to Wednesdays
    • will contain new features and backwards-compatible changes to existing features
    • will contain deprecations to existing features (for removal in the next major version)
  • Major releases
    • will be restricted to Wednesdays
    • will contain breaking changes and removal of features (that were deprecated in an earlier minor version release)


  1. Occasionally, plugin developers will put * as their compatibility string, which means the plugin will always show up as compatible with all versions of NodeBB. Don’t do this—we’ll probably guard against this if it gets abused.
© 2014 – 2023 NodeBB, Inc. — Made in Canada.