Introduce development mode for block editor styles

[helgatheviking]

When a block script is defined in the block.json and registered automatically via register_block_script_handle() the version is pulled from ​the script asset PHP file if it exists. This ensures that the cache is always busted when the file is updated.

Something similar should exist for register_block_style_handle as otherwise it's a total pain to develop editor styles. I just lost a few hours this morning wondering why my styles didn't update even though I am using the @wordpress/scripts package to recompile them on every change.

The answer was ultimately that the version is pulled from the block.json's "version" property which doesn't change while building.

Replacing this:

$version = ! $is_core_block && isset( $metadata['version'] ) ? $metadata['version'] : false;
$result  = wp_register_style(
	$style_handle_name,
	$style_uri,
	array(),
	$version
);

with this:

$block_version = ! $is_core_block && isset( $metadata['version'] ) ? $metadata['version'] : false;
$version = SCRIPT_DEBUG ? filemtime( $style_path_norm ) : $block_version;

$result  = wp_register_style(
	$style_handle_name,
	$style_uri,
	array(),
	$version
);

Should do the trick. The assets file is another option.

[abcd95]

Hi @helgatheviking, Thanks for bringing this up.

I agree that the lack of automatic cache busting during development is problematic on many levels, especially when actively making styling changes and not seeing them reflected.

I will follow up with a proper patch; let me know if it tests well for you.

[abcd95]

The change was first introduced in 56044 and mainly focused on performance improvements.

[helgatheviking]

@abcd95 that patch works great for me!

[gziolo]

That would be great to fix it. I think the logic should be unified between JS and CSS assets. Something like that should work best:

<?php
$default_version = SCRIPT_DEBUG ? time() : false; 
$block_version   = isset( $metadata['version'] ) ? $metadata['version'] : $default_version;
$script_version  = isset( $script_asset['version'] ) ? $script_asset['version'] : $block_version;       

This would cover all possible cases including where the block.json and script.asset.php don't contain tje version property. For styles, everything should look exactly the same but for the style asset when defined. However, it could be break down into two steps as today, reading style asset is not covered. The related issue is tracked in Gutenberg: ​https://github.com/WordPress/gutenberg/issues/56838.

[helgatheviking]

I wasn't sure if the script version updated if changes only happened to the scss. But if so, that sounds great to me.

[gziolo]

A version to adds the same changes for scripts and styles.

[gziolo]

After taking a closer look, I think what @abcd95 provided is the best way to go forward. I extended that for scripts and script modules. The logic covers the case when the asset file doesn't contain version which changes based on the file's content. In every other case when SCRIPT_DEBUG is enabled the version should be randomized on every page load to ensure it never gets served from the cache.

[abcd95]

Replying to gziolo:

After taking a closer look, I think what @abcd95 provided is the best way to go forward.

Thanks @gziolo for reviewing and @helgatheviking for testing the patch. I'm opening a PR to run and check the automated tests and making the review easier.

[jorbin]

In order to give this time for testing and to keep 6.8.1 focused on issues introduced during the 6.8 cycle or intentionally deferred at the end of the 6.8 cycle, I've moved this to 6.8.2

Test Report

This report validates that the indicated patch addresses the issue.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/8725.diff

Environment

• OS: linux
• Web Server: Nginx
• PHP: 8.4.7
• WordPress: TRUNK
• Browser: Chrome
• Active Plugins: none

Actual Results

• ✅ Issue resolved with patch.
• ✅ CSS files now use filemtime() as version parameter when SCRIPT_DEBUG is enabled
• ✅ JS files also properly use filemtime() as version parameter when SCRIPT_DEBUG is enabled
• ✅ Cache busting works correctly - ?ver=xxx parameter changes with each file modification
• ✅ Block editor styles update immediately during development without manual cache clearing

Additional Notes

• Verified that both CSS and JS assets receive proper cache-busting timestamps
• Screenshots captured showing different ?ver=xxx values after file modifications
• Behavior only activates when SCRIPT_DEBUG is true, preserving production performance (version from block.json)
• No conflicts observed with existing block registration functionality

Supplemental Artifacts

Add as Attachment: Screenshots showing different version parameters for CSS and JS files

[audrasjb]

After testing the proposed PR during our agency's contribution day (see @whaze's comment above), it looks like this improvement is quite ready to ship, and it would be quite valuable in a block developer experience perspective. Further review welcome :)

[rollybueno]

Reproduction Report

Description

This report validates whether the issue can be reproduced.

The issue relates to how block editor styles are cached. In development environments, style and script changes may not reflect immediately due to static versioning. The patch introduces timestamp-based versioning when SCRIPT_DEBUG is enabled, allowing changes to reflect immediately without clearing the cache.

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.28
• Server: nginx/1.27.5
• Database: mysqli (Server: 8.4.5 / Client: mysqlnd 8.2.28)
• Browser: Chrome 136.0.0.0
• OS: Linux
• Theme: Twenty Twenty-Five 1.2
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0

Actual Results

1. ✅ Error condition occurs (reproduced).
   • Block editor assets are not cache-busted during development.
   • Changes to SCSS/JS do not reflect unless cache is manually cleared.

Steps to Reproduce

1. Check out the latest WordPress develop repo.
2. Make sure that define( 'SCRIPT_DEBUG', true ); is set.
3. Open a post in the Block Editor.
4. Use browser DevTools to inspect block editor CSS/JS URLs.
5. Confirm static ver is used (e.g., ver=6.9-alpha...) — indicating no cache-busting.

Additional Notes

• This behavior only applies when SCRIPT_DEBUG is enabled.
• Useful in local development when iterating on block styles or scripts.
• On the JS side, some core files like block-editor.js editor.js edit-post.js already appear to include cache-busting based on the ver parameter and may not be affected by this patch.

Supplemental Artifacts

Current trunk:

Editor related CSS:

Editor related JS:

[rollybueno]

Test Report

Description

This report validates whether the indicated patch works as expected.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/8725

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.28
• Server: nginx/1.27.5
• Database: mysqli (Server: 8.4.5 / Client: mysqlnd 8.2.28)
• Browser: Chrome 136.0.0.0
• OS: Linux
• Theme: Twenty Twenty-Five 1.2
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0

Actual Results

1. ❌ Issue not resolved with patch.
   • Block-level styles and scripts continue to use static version strings like ver=6.9-alpha-60093 even when SCRIPT_DEBUG is enabled.
   • DevTools inspection shows no timestamp-based cache busting for style.css or editor-script.js.

Additional Notes

To pull and test the patch:

git fetch upstream pull/8725/head:pr-8725
git checkout pr-8725
npm install
npm run build

• SCRIPT_DEBUG was defined.
• Confirmed that the patch code matches both in the environment and the container. Check the screenshot below..

Supplemental Artifacts

✅ Confirmation of container code matched with ​https://github.com/WordPress/wordpress-develop/pull/8725/files#diff-8c99af92e4ec0fdb307ddd9b42be1e1ef1efe4a9f31287c23f346244dddd1ce9

✖️ Dev console result

✖️ Dev console result

[rollybueno]

Sorry but in my case, the patch from ​https://github.com/WordPress/wordpress-develop/pull/8725 is not working. I might missed something else but I'm 100% sure I have same code base in my Docker container as per report above(In Supplemental Artifacts).

Hey @abcd95 @audrasjb - would mind to check https://core.trac.wordpress.org/ticket/63254#comment:19 and see if I'm doing it right? The block assets still using ver=6.9-alpha-60093-src even though I run build or dev. Maybe I'm looking on wrong files.

[audrasjb]

@rollybueno thanks for the update. Can you share a zip file (or a github repo) containing the code of the custom block you tested with this patch?

[rollybueno]

Oh! I was under the impression that the existing assets would automatically get a timestamp version in the ver parameter after pulling the PR and running the dev build, guess I got that wrong 😅

I'll go ahead and retest using the custom blocks. Thanks for the heads-up!

Replying to audrasjb:

@rollybueno thanks for the update. Can you share a zip file (or a github repo) containing the code of the custom block you tested with this patch?

[sandeepdahiya]

Test Report

Description

✅ This report validates that the indicated patch works as expected.

Patch tested: ​Patch-8725.diff

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.28
• Server: nginx/1.27.5
• Database: mysqli (Server: 8.4.5 / Client: mysqlnd 8.2.28)
• Browser: Firefox 139.0
• OS: Windows 10/11
• Theme: Twenty Twenty-Five 1.2
• MU Plugins: None activated
• Plugins:
  • Custom Style Test Block
  • Test Reports 1.2.0

Actual Results

1. Before patch:

• Registered a custom block with editorStyle pointing to a compiled build/index.css
• Reloaded block editor without cache clear
• index.css loaded without timestamp versioning
• ​checkout the image

2. After patch:

• ✅ The patch worked as expected
• ✅ Observed the CSS file now loads with ?ver=1750687743 based on filemtime()
• ✅ Edited editor.scss, performed npm run build and changes reflected as expected
• ✅ Confirmed via browser DevTools: version query param updates after each build
• ✅ ​checkout the image

[rollybueno]

Test Report

Description

This report validates whether the indicated patch works as expected.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/8725

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.28
• Server: nginx/1.27.5
• Database: mysqli (Server: 8.4.5 / Client: mysqlnd 8.2.28)
• Browser: Chrome 137.0.0.0
• OS: Linux
• Theme: Twenty Twenty-Five 1.2
• MU Plugins: None activated
• Plugins:
  • Block Development Boilerplate 0.1.0
  • Test Reports 1.2.0

Actual Results

1. ✅ Created a custom block using the official guide: ​https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/
2. ✅ Tested on trunk (before applying the patch) and confirmed the ver query parameter for style.css did not use timestamp for cache-busting.
3. ✅ Applied the patch from ​https://github.com/WordPress/wordpress-develop/pull/8725, then ran npm run env:stop and restarted Docker to flush caching.
4. ✅ After restart, modifying the block correctly triggered a version bump in the ver query parameter.
5. ✅ The issue is no longer reproducible after applying the patch.

Additional Notes

• Restarting Docker after applying the patch was essential to invalidate cached data and properly confirm the fix.
• The patch ensures that block assets are properly cache-busted when a custom block is updated during development.

Supplemental Artifacts

TRUNK: You can clearly see here that the custom block ver param is using Version value from plugin header, which in my case is 0.1.0

​https://github.com/WordPress/wordpress-develop/pull/8725 - After checking out to this PR, restarting Docker, I can see the same plugin asset is now using cache-busting patch from this specific line of code: ​https://github.com/WordPress/wordpress-develop/pull/8725/files#diff-8c99af92e4ec0fdb307ddd9b42be1e1ef1efe4a9f31287c23f346244dddd1ce9R332

[rollybueno]

Hey @audrasjb - apologies for the delayed feedback, I’ve only recently had the opportunity to investigate this more thoroughly. I can now confirm that the patch is working as expected based on my latest tests. Please disregard my earlier reproduction test. I’ve consolidated everything into the Test Report shared in comment:24, which includes a clear comparison of behavior before and after applying the patch.

I personally approve this patch 👍

[audrasjb]

In 60355:

Editor: Add cache-busting for block styles on development mode.

This changeset introduces a development mode for block editor styles. When SCRIPT_DEBUG is enabled, block editor styles now use the file modification time as their version, ensuring cache busting during development. This matches the behavior that already exists for block scripts.

Previously, block editor styles only used the version from block.json, which doesn't change during development, causing styles to be cached even after changes.

Props helgatheviking, abcd95, gziolo, whaze, audrasjb, sandeepdahiya, rollybueno.
Fixes #63254.

[audrasjb]

Reopened for 6.8.2 backport consideration.

Second committer sign-off required.

[helgatheviking]

#60163 was marked as a duplicate.

[zunaid321]

This ticket was brought up in a recent bug scrub.

Here's the feedback:

We are currently waiting for a second committer to push the ticket forward.

[audrasjb]

In 60434:

Editor: Add cache-busting for block styles on development mode.

This changeset introduces a development mode for block editor styles. When SCRIPT_DEBUG is enabled, block editor styles now use the file modification time as their version, ensuring cache busting during development. This matches the behavior that already exists for block scripts.

Previously, block editor styles only used the version from block.json, which doesn't change during development, causing styles to be cached even after changes.

Merges [60355] to the 6.8 branch.
Props helgatheviking, abcd95, gziolo, whaze, audrasjb, sandeepdahiya, rollybueno.
Fixes #63254.