Why every WordPress developer should know WP_DEVELOPMENT_MODE

When I first started learning WordPress development, my biggest fear was the White Screen of Death. One moment, my website worked fine. Then I changed some code, and suddenly, the browser showed no content. And since I only got a blank page, it was hard to find out what I did wrong.

Looking back at this, it seems almost silly. But nobody had told me about the WP_DEBUG constant. Or that debugging was a thing and how you went about it.

And with block themes, we are in a similar situation. I got uncountable support requests from students of my free Block Theme Academy course. And the message was always the same: I changed something in theme.json file, and it doesn’t work.

But in most cases, the theme.json file wasn’t the issue. It’s just that these WordPress developers were looking at cached data. And so their changes were not taken into account.

Similar to how I didn’t know about the WP_DEBUG constant, these developers are not aware of the WP_DEVELOPMENT_MODE constant.

In this article, we’ll change this. After reading it, you’ll understand how to set up WP_DEVELOPMENT_MODE for your WordPress development projects, how it benefits your workflow, and how to use it correctly in different scenarios.

What is WP_DEVELOPMENT_MODE?

WordPress introduced the WP_DEVELOPMENT_MODE constant in version 6.3. Similar to other configuration constants, it is meant to be set inside the wp-config.php file. But more on that later.

The concept of a “development mode” in WordPress is relatively recent. This mode changes how WordPress works and is only intended to be enabled on websites inaccessible to the public. So this could be your local development environment or live environments like a staging or development site.

There are five possible values for the constant:

1. An empty string (so ''): this is also the default when the constant is not set in wp-config.php. This means that no development mode is enabled. Use this on production websites.
2. theme: this only enables the development mode for theme-related features. Use this when developing a theme only.
3. plugin: this restricts the development mode to plugin-related features. It’s meant to be used when developing a plugin.
4. all: This enables plugin and theme development modes. Use this when working on a client website with a custom theme and custom plugins.
5. core: Enables development mode for WordPress Core features. This is only useful for open-source contributions to WordPress.

What does WP_DEVELOPMENT_MODE do?

In the current version of WordPress, the development mode constant bypasses certain caching features. In particular, those related to theme.json.

Before version 6.3, WordPress read the theme.json file on every request and parsed its content. The reading of this file, as well as the parsing of its content and merging with other data, is quite an expensive operation.

By implementing a persistent cache, WordPress can use the result of this computation, significantly reducing the time needed to render a page. This makes sense because this data only changes on theme updates or when a user changes the appearance using the Site Editor.

But when developing themes, you want your changes to be applied immediately. And so when the WP_DEVELOPMENT_MODE is set to theme or all, WordPress bypasses these caches, and you always see fresh data.

Therefore, setting the WP_DEVELOPMENT_MODE constant to the correct value is a must-do when starting a new WordPress project.

How to use the WP_DEVELOPMENT_MODE constant

You need to define the WP_DEVELOPMENT_MODE in your WordPress configuration file (wp-config.php). The constant must be defined before WordPress initializes.

Unless you develop a standalone theme or plugin, I recommend setting it to all:

define('WP_DEVELOPMENT_MODE', 'all');Code language: PHP (php)

Setting the constant this way is great if every environment (local, staging, or production) has its dedicated config file.

In specific setups, all environments share a config file, and values are set conditionally depending on the environment. In this case, you can use the following snippet:

if ( defined( 'WP_ENVIRONMENT_TYPE') && WP_ENVIRONMENT_TYPE !== 'production' ) {
    define( 'WP_DEVELOPMENT_MODE', 'all' );
}Code language: PHP (php)

Since you are checking the WP_ENVIRONMENT_TYPE constant, you need to place this snippet after it is defined.

Some hosts use environment variables rather than constants. In that case, the snippet would look like this:

if ( function_exists( 'getenv' ) ) {
    $environment_type = getenv( 'WP_ENVIRONMENT_TYPE' );

    if ( $environment_type !== false && $environment_type !== 'production' ) {
        define( 'WP_DEVELOPMENT_MODE', 'all' );
    }
}Code language: PHP (php)

When in doubt, check your hosting provider’s documentation or reach out to their support.

Common mistakes and how to avoid them

Defining the constant too late

The WP_DEVELOPMENT_MODE constant must be defined before WordPress initializes. Placing it too late in the wp-config.php file or elsewhere in your codebase will render it ineffective.

Leaving it enabled in production

Forgetting to disable WP_DEVELOPMENT_MODE in production can lead to performance issues, as development behaviors are not optimized for live environments.

You can use a plugin like Query Monitor to check the value.

Misunderstanding its scope

As said before, using all as the value covers client projects well.

When contributing to WordPress Core, you might assume that core covers every WordPress open-source project. But if you work on community themes or plugins, you are better off choosing one of these values.

Conclusion

Now that you understand what the WP_DEVELOPMENT_MODE constant is and what it does, you’ll be well-equipped to configure it according to your projects.

And next time you run into problems with stale data, especially when developing a block theme, check this constant.