Skip to main content

Deprecated APIs

Node.js APIs might be deprecated for any of the following reasons:
  • Use of the API is unsafe
  • An improved alternative API is available
  • Breaking changes to the API are expected in a future major release

Deprecation Types

Node.js uses four kinds of deprecations:

Documentation-only

A Documentation-only deprecation is one that is expressed only within the Node.js API docs. These generate no side-effects while running Node.js. Some Documentation-only deprecations trigger a runtime warning when launched with --pending-deprecation flag (or its alternative, NODE_PENDING_DEPRECATION=1 environment variable).

Application (non-node_modules code only)

An Application deprecation for only non-node_modules code will, by default, generate a process warning that will be printed to stderr the first time the deprecated API is used in code that’s not loaded from node_modules. When the --throw-deprecation command-line flag is used, a Runtime deprecation will cause an error to be thrown. When --pending-deprecation is used, warnings will also be emitted for code loaded from node_modules.

Runtime (all code)

A runtime deprecation for all code is similar to the runtime deprecation for non-node_modules code, except that it also emits a warning for code loaded from node_modules.

End-of-Life

An End-of-Life deprecation is used when functionality is or will soon be removed from Node.js.

Revoking Deprecations

Occasionally, the deprecation of an API might be reversed. In such situations, this document will be updated with information relevant to the decision. However, the deprecation identifier will not be modified.

Common Deprecated APIs

Here are some commonly encountered deprecated APIs and their recommended alternatives:

Buffer() Constructor (DEP0005)

Type: Application (non-node_modules code only) The Buffer() function and new Buffer() constructor are deprecated due to API usability issues that can lead to accidental security issues. Alternatives:
// Instead of:
const buf = new Buffer(10);

// Use:
const buf = Buffer.alloc(10);

// Instead of:
const buf = new Buffer('hello');

// Use:
const buf = Buffer.from('hello');

require(‘node:sys’) (DEP0025)

Type: Runtime The node:sys module is deprecated. Please use the util module instead.
// Instead of:
const sys = require('node:sys');

// Use:
const util = require('node:util');

node:punycode Module (DEP0040)

Type: Application (non-node_modules code only) The punycode module is deprecated. Please use a userland alternative instead.
// Instead of:
const punycode = require('node:punycode');

// Use a userland alternative:
const punycode = require('punycode/');

node:domain Module (DEP0032)

Type: Documentation-only The domain module is deprecated and should not be used. It will be removed in a future major version of Node.js. Use AsyncLocalStorage or async_hooks for async context tracking instead.

fs.exists() (DEP0034)

Type: Documentation-only The fs.exists() API is deprecated. Please use fs.stat() or fs.access() instead.
// Instead of:
fs.exists('/path/to/file', (exists) => {
  if (exists) {
    // do something
  }
});

// Use:
fs.access('/path/to/file', fs.constants.F_OK, (err) => {
  if (!err) {
    // file exists
  }
});

util.isArray() (DEP0044)

Type: Runtime The util.isArray() API is deprecated. Please use Array.isArray() instead.
// Instead of:
const util = require('node:util');
util.isArray([]);

// Use:
Array.isArray([]);

util.isBoolean() and Similar (DEP0045-DEP0058)

Type: End-of-Life (many have been removed) Many util.is*() methods have been deprecated and some removed:
// Instead of util.isBoolean()
typeof value === 'boolean'

// Instead of util.isBuffer()
Buffer.isBuffer(value)

// Instead of util.isFunction()
typeof value === 'function'

// Instead of util.isNull()
value === null

// Instead of util.isNumber()
typeof value === 'number'

// Instead of util.isString()
typeof value === 'string'

SlowBuffer (DEP0030)

Type: End-of-Life The SlowBuffer class has been removed. Please use Buffer.allocUnsafeSlow(size) instead.
// Instead of:
const slowBuf = new SlowBuffer(10);

// Use:
const buf = Buffer.allocUnsafeSlow(10);

util._extend() (DEP0060)

Type: Runtime The util._extend() API is deprecated. Please use Object.assign() instead.
// Instead of:
const util = require('node:util');
const target = {};
const source = { a: 1 };
util._extend(target, source);

// Use:
const target = Object.assign({}, source);

Unhandled Promise Rejections (DEP0018)

Type: End-of-Life Unhandled promise rejections are deprecated. By default, promise rejections that are not handled terminate the Node.js process with a non-zero exit code. To change the way Node.js treats unhandled rejections, use the --unhandled-rejections command-line option.
// Always handle promise rejections:
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
});

// Or use try/catch with async/await:
async function example() {
  try {
    await someAsyncOperation();
  } catch (err) {
    console.error('Error:', err);
  }
}

Detecting Deprecations

You can detect when deprecated APIs are used by:
  1. Using command-line flags:
    • --throw-deprecation - Throw errors when deprecated APIs are used
    • --no-deprecation - Suppress deprecation warnings
    • --trace-deprecation - Show stack traces for deprecations
    • --pending-deprecation - Emit warnings for pending deprecations
  2. Listening to the warning event:
process.on('warning', (warning) => {
  if (warning.name === 'DeprecationWarning') {
    console.warn(warning.name);
    console.warn(warning.message);
    console.warn(warning.stack);
  }
});

Best Practices

  1. Keep your code up to date - Regularly update your code to use non-deprecated APIs
  2. Test with deprecation warnings - Run your tests with --pending-deprecation to catch future deprecations early
  3. Monitor warnings in production - Log deprecation warnings to track which deprecated APIs your application uses
  4. Review Node.js release notes - Check for newly deprecated APIs when upgrading Node.js versions
  5. Use linters - Tools like ESLint can help detect usage of deprecated APIs

Additional Resources

For a complete and up-to-date list of all deprecated APIs, including their deprecation codes (DEP0001, etc.), refer to the official Node.js documentation at nodejs.org/api/deprecations.html.