Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

The Node.js stability index

What the stability levels mean in the Node.js API (deprecated, experimental, stable, legacy), how warnings surface in code, and how to depend on APIs safely.

Not every part of the Node.js API carries the same promise. The documentation labels each API with a stability index, which tells you how much you can rely on it staying as it is. Reading that label before you build on something saves painful upgrades later.

The levels are numbered 0 to 3:

Level Name Meaning
0 Deprecated Do not use. It may be removed in a future major version.
1 Experimental Not subject to semantic versioning; may change or be removed in any release. Not for production without care.
2 Stable Compatibility with the npm ecosystem is a high priority; breaking changes happen only with notice and in major versions.
3 Legacy Still supported, but a better alternative exists. Not scheduled for removal, but not recommended for new code.

Experimental APIs are further split into sub-levels such as 1.0 (early development), 1.1 (active development), 1.2 (release candidate) and, in some documentation, a level for a feature that is nearly stable. Treat the labels as direction of travel: the higher the number, the closer to stable.

NODE
process.on('warning', (w) => console.log(w.name, w.code));

Try it

Node.js Deprecations surface as warnings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Your own deprecations and warnings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Usage notes

  • Check the label before you depend on an API. Level 2 is safe for production; anything at level 1 needs a plan for change; level 0 needs a migration.
  • Experimental features often print a warning (ExperimentalWarning) the first time you load or use them. The warning names the feature; silence it only after you have decided to accept the risk (--disable-warning=ExperimentalWarning).
  • Experimental features may need flags. Some are off by default and require --experimental-...; others are on by default but still unstable, for example in a given release a module might work without a flag yet still be level 1.
  • Features graduate. An experimental API often becomes stable within a few releases, sometimes with changes. Re-read the docs after each major upgrade.
  • Deprecation has stages: documentation-only, runtime (a warning is printed), and finally end-of-life (removed). Each deprecation has a DEPxxxx code you can look up.
  • Warnings go to stderr. Control them with --no-deprecation, --trace-deprecation, --throw-deprecation and process.noDeprecation; use --throw-deprecation in test suites to catch problems early.
  • Do not rely on undocumented behavior, internal modules (node:internal/...) or properties starting with an underscore; they are not part of any stability promise.
  • Libraries should avoid experimental APIs unless they feature-detect them, because a consumer on another Node version could break.