@wordpress/deprecated

Deprecation utility for WordPress. Logs a message to notify developers about a deprecated feature.

Installation

Install the module

npm install @wordpress/deprecated --save

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Hook

The deprecated action is fired with three parameters: the name of the deprecated feature, the options object passed to deprecated, and the message sent to the console.

Example:

import { addAction } from '@wordpress/hooks';

function addDeprecationAlert( message, { version } ) {
    alert( `Deprecation: ${ message }. Version: ${ version }` );
}

addAction(
    'deprecated',
    'my-plugin/add-deprecation-alert',
    addDeprecationAlert
);

API

default

Logs a message to notify developers about a deprecated feature.

Usage

import deprecated from '@wordpress/deprecated';

deprecated( 'Eating meat', {
    since: '2019.01.01',
    version: '2020.01.01',
    alternative: 'vegetables',
    plugin: 'the earth',
    hint: 'You may find it beneficial to transition gradually.',
} );

// Logs: 'Eating meat is deprecated since version 2019.01.01 and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'

Parameters

• feature string: Name of the deprecated feature.
• options [DeprecatedOptions]: Personalisation options

logged

Object map tracking messages which have been logged, for use in ensuring a message is only logged once.

Type

• Record< string, true >

Unit testing deprecations

Each deprecation message is logged only once per loaded instance of this package. The exported logged object tracks the full message text. Resetting a console spy does not clear this state.

Gutenberg’s internal Vitest setup clears logged before each test in Node, jsdom, and Browser Mode. Suites do not need their own deprecation-history cleanup. If every test that triggers a deprecation asserts the warning, no interaction with logged is needed. A message still logs only once within a test. See Expected console calls.

For a suite that exercises a deprecated feature, mark its message as logged in beforeEach to suppress it during tests of other behavior. Delete that entry before testing the warning itself.

This example uses Vitest and the toHaveWarnedWith matcher provided by Gutenberg’s test setup:

import { beforeEach, describe, expect, it } from 'vitest';
import deprecated, { logged } from '@wordpress/deprecated';

const DEPRECATION_MESSAGE = 'legacyFeature is deprecated.';

describe( 'legacyFeature', () => {
    beforeEach( () => {
        logged[ DEPRECATION_MESSAGE ] = true;
    } );

    it( 'warns that the feature is deprecated', () => {
        delete logged[ DEPRECATION_MESSAGE ];
        deprecated( 'legacyFeature' );

        expect( console ).toHaveWarnedWith( DEPRECATION_MESSAGE );
    } );
} );

Setting a logged entry also prevents the deprecated action from firing. Leave the entry absent when testing that action.

If your test setup does not clear logged, an earlier test can prevent a later test from observing the same warning. Delete the entries for messages your suite uses in beforeEach and afterEach to keep tests independent. For tests that suppress a warning, set its entry in beforeEach instead of deleting it. Limit cleanup to the messages the suite uses.

Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.