Blocks: Display browser console warnings for blocks with apiVersion below 2#70783
Merged
Blocks: Display browser console warnings for blocks with apiVersion below 2#70783
Conversation
t-hamano
added
[Type] Developer Documentation
|
Size Change: +3 B (0%) Total Size: 1.91 MB
ℹ️ View Unchanged
|
t-hamano
changed the title
t-hamano
force-pushed
the
warning-block-api-version
branch
from
921a9e3 to
8d91750
Compare
t-hamano
commented
Jul 19, 2025
Contributor
Author
|
One concern is that if the |
t-hamano
changed the title
t-hamano
requested review from
ajitbohra,
fabiankaegy,
juanmaguitar and
ndiego
as code owners
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
t-hamano
added
Backwards Compatibility
fabiankaegy
reviewed
Jul 21, 2025
jsnajdr
reviewed
Jul 21, 2025
| if ( settings.apiVersion <= 2 ) { | ||
| warning( | ||
| 'Block API version is less than 2. This means that the post editor may be rendered outside the iframe. Since all editors are planned to work as iframes in the future, set the `apiVersion` field to 3 and test the block inside the iframe editor. See: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/#version-3-wordpress-6-3' | ||
| ); |
Member
There was a problem hiding this comment.
The warning should say exactly which block is being registered. There can be easily hundreds of registered blocks, how do I find which is the bad one?
Also, be prepared there will be a lot of warnings once this is active 🙂 I was playing with apiVersion some time ago and noticed that there are many 3rd party blocks that don't declare apiVersion at all, and it defaults to 1.
Mamaduka
reviewed
Jul 22, 2025
Contributor
Author
If we could make API version 3 the default, we wouldn't need this mock 🤔 See #70750 (comment) |
Member
|
I think making API version 3 the default might count as a breaking change, since it might break plugins that aren't compatible with iframed editors. |
youknowriad
approved these changes
Jul 31, 2025
Contributor
youknowriad
left a comment
youknowriad
left a comment
There was a problem hiding this comment.
We should have done this a long time ago. Thanks Aki.
Contributor
|
I do think we should make it default as well. |
Member
I believe this was discussed here also but it would be a breaking change since there are many blocks out there that don't specify an |
Contributor
|
yes, maybe something that should happen later after this log is out there. Should we clarify that in the logged message too? |
Contributor
Author
|
We may be able to migrate in stages. Since the default API version for blocks without an explicitly defined apiVersion became 1 by #70750, many developers will see browser warnings in WP 6.9 once this PR is merged. We might be able to push the default API version to 3 in WP 7.0, taking into account developer feedback we'll get on WP 6.9. P.S. As a follow-up, I plan to disallow anything other than 3 in the block.json schema, just like theme.json. |
Mamaduka
reviewed
Aug 1, 2025
|
Flaky tests detected in 57f5487. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/16719990172
|
4 tasks
Contributor
Author
|
@Mamaduka Thanks for the review!
I agree. I've added it as one of the tasks on the list at the bottom here: #70743 (comment) |
Contributor
Author
|
I noticed that the Widget Area block is running in version 1, which is causing the browser warning. This block is very specific, but I'll try to see if we can migrate it to version 3. 
|
24 tasks
4 tasks
|
This warning does not appear in WordPress 6.9, because wp.warning is set to a noop function. Is this intentional? This wasn't documented anywhere in the WP 6.9 notes, and seems to make it rather pointless for developers wanting to check if a site needs updates made or not. |
Member
|
@smerriman, similar warnings are only displayed when |
Contributor
Author
Thak't true. gutenberg/packages/warning/src/index.ts Lines 28 to 31 in ca85e42 I think that point wasn't clear in the dev note, so I'll update it. |
Contributor
|
@t-hamano should we make these warnings more prominent? alway trigger them even if script_debug is false (using deprecated in stead of warning) |
Contributor
Author
I don't have a strong opinion, but I think there are many users who use a lot of blocks with the block API version 2 or lower. In that case, they might be surprised by the large number of warnings. What do you think? 
|
Contributor
I think this is what we need to force devs to migrate. I also think we need to do this on a minor WP release ideally 6.9.1 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See #70743 (comment)
What?
If the API version of the block being registered is below 2, a browser warning error will be displayed.
Why?
The Block API version is referenced as a factor in determining whether the Post Editor should run as an iframe or not. We plan to move the Post Editor completely to an iframe in the future, so we need to encourage developers to test their products with the iframe editor.
How?
More developer-friendly log messages or documentation are welcome!
Why?
The API version of the block below 2 is one of the factors that prevents the post editor from working as an iframe. Let's encourage developers to change their API version to 3 and test their custom blocks in the iframe editor.
Testing Instructions
Run the following code via your browser console and check the displayed message.
Also check out the linked documentation: https://github.com/WordPress/gutenberg/blob/warning-block-api-version/docs/reference-guides/block-api/block-api-versions.md#version-3--wordpress-63
Testing Instructions for Keyboard
Screenshots or screencast