Provide a way for classic themes to use `wp-block-library` even when loading block assets only for blocks that actually render on a page

[fabiankaegy]

This ticket is coming out of a [Discussion in the Make WordPress Slack](​https://wordpress.slack.com/archives/C02QB2JS7/p1724866722880979). And it it tangentially related to #61958

As it stands today, classic themes load all the stylesheets of any blocks regardless of whether they are used on the page or not. This is partially due to the fact that for a long time the core blocks all had their styles bundled into one wp-block-library stylesheet.

In order to change this behavior for core blocks a new flag wp_should_load_separate_core_block_assets was introduced which is enabled by default for block based themes. When this flag is enabled, core will no longer load the wp-block-library stylesheet but rather load individual stylesheets for only the blocks that are rendered on the page. Using the should_load_separate_core_block_assets filter classic themes can also opt into this behavior which does in theory solve this problem.

However I am proposing that we add an additional flag that would allow classic themes to opt into the conditional loading of stylesheets without opting into the wp-block-library change.

The reasons why I think this is important is that the refactor existing sites have to go through to move their large CSS codebases over to no longer depend on the loading order / specificity implications of having the wp-block-library CSS is a major effort. So it is going to take time for those sites to move over to having block specific stylesheets.

In the meantime it would already be an arguably even larger performance improvement for these sites to no longer load the separate stylesheets of blocks we already have when they are not needed on the current page.

Third party blocks often have much larger CSS files associated with them. Because they might for example load an entire Maps library, or other really large features.

[fabiankaegy]

CC: @flixos90 since you participated in the conversation in Slack :)

[flixos90]

@fabiankaegy Thank you for opening the ticket.

Based on reading the ticket description and our previous conversation on Slack, I wonder whether this would be more clear if phrased differently:

• The ticket title/summary is currently describing something that's already possible today, via wp_should_load_separate_core_block_assets().
• I believe what you're proposing though is more about being able to opt in or opt out of using individual core block stylesheets (vs using the one wp-block-library stylesheet), independently of whether block assets are loaded on demand or not.
• Related to #61958, I think this conversation is confusing because wp_should_load_separate_core_block_assets() does not what its name indicates. Today it is responsible for opting in to load block assets on demand (rather than everywhere unconditionally). By doing that it also opts in to using individual core block stylesheets instead of wp-block-library. So as far as I understand, you'd like to be able to control the latter separately.

Did I get that right?

[fabiankaegy]

@flixos90 That is correct 👍 Thank you for summarizing it in a much better way.

It really comes down to decoupling the wp-block-library from the independant loading of block stylesheets for third party blocks.

[flixos90]

@fabiankaegy Thanks for confirming. I'll rename the ticket to clarify.

A potential solution for this could be (I'm not going to talk about function names so that we can focus on the solution only):

• There's a function (and filter) "A" that controls whether to load block assets on demand (we already have that today).
• There could be another function (and filter) "B" that controls whether to use individual core block stylesheets instead of wp-block-library.
  • While today's function name sounds like it would do that, that's not actually its primary purpose (see #61958).
• Function "B" would by default rely on the output of function "A". In other words: If block assets are loaded on demand, individual core block stylesheets are used. But the filter in "B" could be used to change that, without changing the output of function "A".
• With this kind of setup, everything would work the same way as today by default. The enhancement though would be that you can change the two configurations independently of each other.

The two new possible scenarios that aren't supported in Core today would be:

• Block assets are loaded on demand, but wp-block-library is used: In this scenario, whenever any core blocks is encountered, the wp-block-library stylesheet would be enqueued.
• Block assets are loaded unconditionally, but individual core block stylesheets are used: In this scenario, the individual core block stylesheets would simply be enqueued everywhere.

I don't feel strongly about whether or not it's a good idea to support this. Generally, using wp-block-library is wasteful when it comes to performance (and sustainability). But I acknowledge that lots of third-party code depends on wp-block-library today and it'll take time to migrate away from that. When in that situation, today you will have to load all block assets everywhere, even third party blocks that have nothing to do with wp-block-library. Essentially, today Core only allows you to go all in or get none of the benefits of loading on demand. So differentiating between whether to load block assets on demand and whether to use wp-block-library might be a worthwhile enhancement.

@gziolo @aristath I'd be curious to get your perspective.

[flixos90]

While related to my proposal in 4 I proposed to rename (deprecate) the existing wp_should_load_separate_core_block_assets() function and the related filter in #61958, we can probably go a less disruptive route by implementing my idea from 4 the other way around:

• Today, wp_should_load_separate_core_block_assets() controls both whether to load separate block assets as well as whether to "lazy-load" block assets for only the blocks that are used in the current page.
• To retain backward compatibility, we will need to retain that behavior. We can however introduce a new function, e.g. wp_should_load_block_assets_on_demand(), which would by default rely on the output of wp_should_load_separate_core_block_assets(), but could separately be modified via filter.
• This new function will effectively allow use of the combined wp-block-library asset even while loading only block assets needed on the page. It would be achieved by filtering the result of wp_should_load_separate_core_block_assets() to false and filtering the result of wp_should_load_block_assets_on_demand() to true.

Worth noting: I still think wp_should_load_separate_core_block_assets() is not a great name for the function, specifically the fact that it includes the word "core", but it's not at all specific to Core blocks. But renaming/deprecating the function would be quite disruptive, so that is a discussion for another time and another ticket.

• Introduces wp_should_load_block_assets_on_demand() with filter 'should_load_block_assets_on_demand'.
• By default, it relies on the output of the existing wp_should_load_separate_core_block_assets() (and its filter 'should_load_separate_core_block_assets'). This ensures backward compatibility.
• Having the separate filters allows theme developers to make distinct decions on the following:
  • Do I want to load individual stylesheets for Core blocks or a single combined wp-block-library stylesheet for all Core blocks?
  • Do I want to have block scripts and stylesheets loaded on demand only for blocks used, or have all blocks scripts and styles loaded unconditionally?
• By default, the decision on the first will still affect the latter too, but by having the separate filters it is possible to control both when that 's needed. See the Trac ticket for more context on such use-cases.
• For block themes, loading all block scripts and styles unconditionally has (almost?) no benefit, which is why they have always opted in to the existing filter. This PR expands that to also opt in to the new filter by default. This ensures that, for block themes, even if the theme developer deactivates use of wp-block-library, scripts and stylesheets are still loaded on demand.
• The PR adds inline comments in a few places to clarify related behaviors that may otherwise be unclear or confusing when reading the code.

Trac ticket: https://core.trac.wordpress.org/ticket/61965

cc @fabiankaegy, would appreciate your feedback!

The code changes look good to me in general. I like how this brings clarity to the existing method wp_should_load_separate_core_block_assets() that covered more use cases than anticipated by only looking at its name. A new method works with all types of blocks as the old one, but the name for the method and filter removes all the confusion that existed.

The only clarification I'm looking for is shared in ​https://github.com/WordPress/wordpress-develop/pull/8234#discussion_r1944654982. I'd like to better understand while the legacy filter is ignored for the block themes by always defaulting to true.

[flixos90]

In 59823:

Editor: Introduce wp_should_load_block_assets_on_demand() with filter 'should_load_block_assets_on_demand'.

This function and filter complement the existing wp_should_load_separate_core_block_assets() with filter 'should_load_separate_core_block_assets', which until now was responsible for two different purposes:

1. Loading separate stylesheets for Core blocks, instead of a combined wp-block-library stylesheet (as the name indicates).
2. Loading block scripts and stylesheets on demand only if the blocks are included in the page (not indicated by the name).

The new function and filter handles exclusively the 2nd purpose, making it possible to individually adjust both behaviors. For backward compatibility, the return value of wp_should_load_separate_core_block_assets() is used as the filterable default for wp_should_load_block_assets_on_demand(). Yet, the two filters can now be individually be controlled: For example, a site owner that wants to keep loading the combined wp-block-library stylesheet can now do so without giving up on the ability to load block scripts and stylesheets on demand.

Block themes now opt in by default to both features, similar to how they were already doing before via just the one filter. This way, block themes that opt out of loading separate stylesheets for Core blocks will still benefit from loading block scripts and stylesheets on demand, which in the case of block themes is strongly recommended.

Props fabiankaegy, flixos90, gziolo.
Fixes #61965.