Block lazy loading

[jsnajdr]

Motivation

A WordPress site with a few popular plugins, like Jetpack and WooCommerce, can have hundreds of registered and available blocks. And load all their scripts and styles into the editor, upfront, during the editor initialization. But a typical post uses only a handful of blocks, and it can be shown that the redundant blocks code typically constitutes about 50% of the editor size.

Solution

The solution we're proposing here is to load block scripts and styles asynchronously, just in time. On initial load, the editor would know only a very basic static info about all blocks, like their names, titles, icons. This is the "bootstrap" info sent by the server in the editor's HTML document That's enough to show a basic inserter UI for the block, and also to load the full block code when needed. The full block load would be triggered only just before a block is about to be created. That can happen when a content parser (for post or block pattern) encounters a block of given type, when a block is inserted from inserter, or created by a block transform.

To implement this solution, we need to make three broad changes in the Gutenberg editor:

1. Server-side registration of blocks needs to be more complete that it is today. Blocks need to correctly declare the scripts and styles they want to load, and fill all necessary fields, like title or description, on the server.
2. The client app needs to have the capability to load scripts and styles dynamically, when it needs them. Instead of statically enqueuing them all on the server. The server needs to provide some kind of "importmap" or "module manifest", and the client needs a "loader" that can load a script with a given handle.
3. Many Gutenberg block-related APIs which are now synchronous will have to become asynchronous. Like the select( 'core/blocks' ).getBlockType() selector, or the createBlock and switchToBlockType functions from the blocks package, or transform functions on block transforms. Keeping a backward compatibility with the old sync versions will be a major challenge.

Now let's expand on these three themes in more detail.

Server-side block registration

A typical server side block registration call looks like this:

register_block_type( 'example/block', array(
  'render_callback' => 'example_block_render_callback'
  'style' => 'file:./style.css',
) );

This is the most minimal server registration, and it provides only the information that the server really needs to render the block when it appears in content. The render_callback is a PHP function that generates the block's dynamic HTML content. The style field is more interesting for us. It defines the style that should be enqueued when the block is rendered. When the file: syntax is used, it is a two step process. During the block registration, the referenced file is registered, using wp_register_style, with an auto-generated example-block-style handle. Then, when the block is being rendered, WordPress will call wp_enqueue_style( 'example-block-style' ) to include the block's style in the rendered page.

An alternative way to register the style is to register the handle yourself:

wp_register_style( 'example-block-style', $style_filename );
register_block_type( 'example/block', array(
  'style' => 'example-block-style'
) );

You register the style, then register the block, and then WordPress can enqueue the styles declared by the when it decides so. Note that here, for frontend styles and scripts, the assets are already enqueued dynamically, only when needed.

To register a full block in the browser client, someone needs to call the JS function registerBlockType. This is typically done by an "editor script", declared during server registration:

register_block_type( 'example/block', array(
  'editor_script' => 'example-block-editor-script'
) );

When generating the HTML page for Post or Site Editor, WordPress will loop through all registered blocks and will enqueue all their editor_script and editor_style handles.

The client-side block registration can be also completely decoupled from server-side registration. WordPress can simply enqueue a "random" script on the editor page, an if the script contains calls to registerBlockType, blocks are registered. This is unfortunately fairly typical. Not even Core blocks declare their editor_scripts on individual blocks. There is one wp-block-library script that bundles all Core blocks definitions, and the connection between the server-side block definitions and this script is not declared anywhere. Plugins like Jetpack or WooCommerce register their blocks the same way.

If editor scripts and styles are to be loaded dynamically, this practice will need to be abandoned. Connection between a server-side block and client-side editor script needs to be declared and known, otherwise the "load the editor script for block X now" task cannot be performed.

Note that it is not strictly necessary that each block has its own individual, unique editor script. It's OK if multiple blocks declare the same editor_script, like:

register_block_type( 'core/paragraph', array(
  'editor_script' => 'wp-block-library'
) );
register_block_type( 'core/list', array(
  'editor_script' => 'wp-block-library'
) );
register_block_type( 'core/quote', array(
  'editor_script' => 'wp-block-library'
) );

Here, dynamically loading any of the three registered Core block will trigger a load of the entire Block Library script, and registration of all Core blocks. This loads much more code than we really need for one individual blocks, but on the other hand it can be a very good tradeoff to bundle multiple blocks into one script. It's very similar to how JS bundlers like webpack bundle multiple modules into one chunk, trying to optimize things like number of parallel HTTP requests etc.

Generating an importmap

When blocks correctly declare and register all their script and style handles, they can be automatically enqueued, with wp_enqueue_script and wp_enqueue_style, when generating the HTML page for the editor. But we don't want to do that, that's the existing sync block loading, and we want to be async. Instead, the server should expose to the client all the information that the client needs to load a given script handle, at any time when it needs it.

For WordPress scripts, the registered information looks like this:

'example-block-editor-script': {
  src: 'wp-content/plugins/example/editor.min.js',
  ver: '1.2.3',
  deps: [ 'wp-element', 'wp-i18n' ]
}

If the client knows this information, it can load the script. It will:

1. first load the dependencies, i.e., the scripts with handles wp-element and wp-i18n
2. then load the actual script, from URL wp-content/plugins/example/editor.min.js?ver=1.2.3

There can be a "loader" function, called like this:

await loadScript( 'example-block-editor-script' );
const block = getBlockType( 'example/block' );

After awaiting the loadScript call, we are sure that the example/block has been registered and can work with it.

Loading styles works exactly the same way, the server sends the client the information about registered script handles, and a loadScript function can load them.

ESM importmaps

Ideally, the "information that the client needs to load a given script handle" would be standard ESM importmap declared as part of the editor HTML page:

<script type="importmap">
  {
    "imports": {
      "example-block-editor-script": "./wp-content/plugins/example/editor.min.js?ver=1.2.3"
    }
  }
</script>

and loading the script would be done with a standard import statement:

await import( 'example-block-editor-script' );
const block = getBlockType( 'example/block' );

But there are many practical obstacles that make this approach only aspirational at this moment:

1. How do we load styles as ESM modules? CSS modules are not standardized yet.
2. How do we load the dependencies automatically? The script would need to be a module itself, with embedded import statements in its source.
3. How do we deal with inline scripts added with wp_add_inline_script? WordPress commonly uses that to add additional data for a script, typically some config setup of the given library, or its localization.
4. register_block_type can declare multiple script handles for a given script, like viewScript: [ 'file:./view.js', 'file:./view.modal.js' ]. Both scripts needs to be loaded, i.e., a single import( 'example-block-view-script' ) call should load two different URLs. Similar to dependencies.

WordPress blocks and scripts would need some major architectural cleanup before ESM importmaps are feasible.

Bootstrapped server info

The server-side registration info is available on the client as a result of the bootstrapServerSideBlockDefinitions function call, and also on the /block-types REST endpoint. The client can therefore access some basic info about blocks even without loading their scripts. For example, to make the block inserter work, we need this block info to be properly filled:

name
title
description
(icon)
(example)
category
keywords
supports.inserter
parent
ancestor

The block inserter needs this info to:

• determine whether the block can be inserted at a particular place, as a child of an existing parent block, i.e., whether it should be shown in the block inserter at all. The supports.inserter, parent and ancestor fields are needed for that.
• actually show the block info in the inserter UI. That's where fields like title, description or icon are needed.

We also need the same info for all block variations. The variations are often shown in the inserter as a regular block.

All the above fields are static strings or arrays that are easy to registered on the server, except icon and example.

Icon

Block icons currently can't be registered on the PHP server, because they can be generic React components. A JSX element or a JSX component (function or class constructor) is a valid icons. They can't be expressed as PHP code and sent across network in a serializable form. We'll need to deprecate them, and support only Dashicons (referenced by a string identifier) and SVG, or more precisely, image URLs. The React components are almost always simple <svg> elements, so they should be easy to migrate to static strings or data: URLs. Blocks registered in the WP.org Block Directory also need to have a web-compatible icon registered, so this is a reasonable requirement.

Example

The example field is a static structure of block attributes and inner blocks, possible to register on a PHP server, but it doesn't make much sense. The example data are used to actually create a block with given attributes, so all sensible operations require the block to be loaded anyway. There's no benefit from the server-side registration. In Gutenberg UI, the example is used in the BlockPreview popup shown when the user hovers over the block. So, displaying the inserter is possible with server-side data, but when hovering over the displayed inserter, blocks will get fully loaded in order to display their previews.

Registering the example field on the server could be useful only if we wanted to generate the preview markup on the server. That's possible, the server knows everything it needs to know to generate a fully styled preview. It's similar to server-side rendering of embeds. Could be also a REST endpoint.

When is a full block load triggered?

• parsing content into blocks when loading post
• parsing block patterns, either for insertion or for determining whether they are insertable (depends on permissible parent-child block type relationships).
• creating a block (createBlock)
• switching to a block type (switchToBlockType)

All the affected APIs (mostly in the @wordpress/blocks package) will need to be switched to async function, returning promises.

Block transforms

Block transforms are currently registered as a transform property of a block registration, but this is an architectural design error. Transforms are animals completely independent from blocks. I should be able to register a block transform individually. A block transform says "I can transform a block of type X (or multiple blocks) into a block of type Y", and we don't need block type X or Y to be loaded in order to register or perform such a transform. The loading will be done by the createBlock calls inside the transform or convert functions.

[jeherve]

This makes a lot of sense, for Core but also for third-party plugins as you mentioned. Thanks for bringing this up!

For example, to make the block inserter work, we need this block info to be properly filled

Should a block preview be available as well? I think previews can provide a lot of value. As the saying goes "a picture is worth a thousand words" ; I could see it being just as useful as the block description for authors looking to insert a block in their content.
That said, I realize that loading block previews is probably bringing way too much information into the data we'll need to load.

[jsnajdr]

Yes, the block preview is an important special case. It's generated from the example field of the registered block, and shown in a popup window. But to create a visible HTML markup from these example data, you need to load the full block anyway, so including the example data in the bootstrapped info doesn't help.

It would be different if we wanted to render the block previews on the server. The server has all the capabilities it needs to generate a fully styled block preview, and serve it into an iframe, for example.

I added a section to the main document that addresses this.

[gziolo]

example is quite special as it rarely lands in block.json because, many times, folks want to include translations and, therefore, put them in JavaScript files paired with function helpers from @wordpress/i18n. However, there are times when you need to assemble examples based on the data available on the server and it's simpler to share it with the client during block registration. One of the examples would be block variations generated for Template Parts block:

gutenberg/packages/block-library/src/template-part/index.php

Lines 235 to 260 in 908bc4a

	foreach ( $template_parts as $template_part ) {
	$variations[] = array(
	'name' => 'instance_' . sanitize_title( $template_part->slug ),
	'title' => $template_part->title,
	// If there's no description for the template part don't show the
	// block description. This is a bit hacky, but prevent the fallback
	// by using a non-breaking space so that the value of description
	// isn't falsey.
	'description' => $template_part->description || ' ',
	'attributes' => array(
	'slug' => $template_part->slug,
	'theme' => $template_part->theme,
	'area' => $template_part->area,
	),
	'scope' => array( 'inserter' ),
	'icon' => isset( $icon_by_area[ $template_part->area ] ) ? $icon_by_area[ $template_part->area ] : null,
	'example' => array(
	'attributes' => array(
	'slug' => $template_part->slug,
	'theme' => $template_part->theme,
	'area' => $template_part->area,
	),
	),
	);
	}
	return $variations;

---

Now, the separate story is how the block previews work today. They use edit implementations exposed by all blocks rather than save + render/renderCallback, which would be a more accurate representation of what people see when visiting the website. As part of the efforts, we should seek ways to refactor the code to remove the need to always use edit, which is usually the biggest chunk of the block's code loaded in the browser.

[jsnajdr]

it rarely lands in block.json because, many times, folks want to include translations and, therefore, put them in JavaScript files

Translations in block.json are also being done server-side, for fields defined in the block-i18n.json schema. Extending that also to the example field is possible. It would be significant expansion of what the translate_settings_using_i18n_schema function can currently do, as example is a dynamic nested structure, but it can be done.

They use edit implementations exposed by all blocks rather than save + render/renderCallback

Yes, I was suprised to learn that previews use the edit implementations, just marking the rendered HTML elements as inert. I would expect an iframe with the markup produced by save. The edit components have been used ever since the beginning in #4246. Maybe @youknowriad knows if there is any principal reason for that.

For async block loading, however, I don't think the edit vs save distinction is important. Loading edit and save separately is too fine granularity. We'll probably need only to distinguish only between the "bootstrapped" static data and "full" data.

[youknowriad]

The principal reason previews use "edit" is dynamic blocks. "save" render nothing for these blocks. So it's either: "edit" or "frontend rendering" in an iframe which had its complexities too.

[gziolo]

@jsnajdr, thank you for opening this discussion. It's a topic that's been explored several times since 2017. There is an existing tracking issue that was used in the past to coordinate efforts: #2768.

I think you provided an excellent summary of the problem and outlined all the steps required to enable async loading for blocks. I only wanted to extend some information. We invested efforts into offering the block.json metadata file format to eventually enforce server-side registration so we could use that information with the block inserter without the need to enqueue the JavaScript and CSS files. In fact, it's the underlying mechanism to provide details used to list blocks when browsing results from Block Directory. We defer the moment for installing the plugin with the block until it gets inserted into the editor. You can also check how blocks installed from the Block Directory get activated without a page reload:
https://github.com/WordPress/gutenberg/blob/trunk/packages/block-directory/src/store/load-assets.js.
One important note here is that lazy loading for core blocks, if necessary, might be way easier because all the script dependencies they use today are already present on the page. The same applies to blocks from Block Directory, as it's one of the requirements when submitting plugins. However, for 3rd party blocks, you don’t only need to know which styles and scripts the block needs but also all the missing dependencies those assets require on the page. There is a related WP core ticket that describes the problem more in-depth: https://core.trac.wordpress.org/ticket/48654. There is also a PR with an attempt to expose scripts and styles with a REST API endpoint: #21244.

[jsnajdr]

However, for 3rd party blocks, you don’t only need to know which styles and scripts the block needs but also all the missing dependencies those assets require on the page.

Yes, that needs to be a part of any correct implementation of an "importmap". For a given script handle, the server must expose all the information needed to load that script handle. That's not only the URL but also a list of the dependent script handles. The browser client then can load all the necessary assets in the right order.

The trac:48654 ticket has a REST API endpoint implementation that exposes all this info. Today the REST endpoint idea is outdated, and the ideal solution is to create an ESM importmap, which resolves a script handle to an URL:

"my-block-editor-script": "/assets/my-block/editor.js?ver=1.2.3"

and the editor.js module should import its dependencies at the beginning:

import dep1 from 'dep1-script';
import dep2 from 'dep2-script';

...

What I currently see as a realistic solution, one that can handle all the WP quirks (inline scripts etc), is a webpack-like "manifest", custom JS code that contains all the info needed to load a script. That's what the #51778 prototype PR implements. It doesn't implement support for dependencies yet, but that can be easily added.

[jsnajdr]

@youknowriad asks in #51778 (review):

The last thing is about the "import map" and "loader", what are your thoughts on trying import maps
I'm writing about this in the "Generating an importmap" section above, and here are some more details.

First of all, the exact implementation of the import map and the loader is an "implementation detail", in the sense that it can be easily encapsulated and replaced at will with a different implementation. There is the server-side gutenberg_emit_importmap function, which can emit either <script> with custom code or standard <script type="importmap">. Browser-side, there are loadScript and loadStyle functions that can be implemented either as old-fashioned createElement( 'style' ) code, or as a wrapper for native import. That's all. Whether we use one or the other is not at all fundamental.

My goal was to have a prototype that really works, and I started with something that's simple and that I'm familiar with. In order to switch to native importmaps, here are the problems that need to be solved.

How to load styles? Until very recently, I thought this is the major obstacle that blocks importmap adoption. We need to load not only JS modules, but also CSS stylesheets. Only after discussing import assertions in #53470 I learned that Chrome natively supports CSS modules! I can do:

async function loadStyle( handle ) {
  const { default: stylesheet } = await import( handle, { assert: { type: 'css' } } );
  document.adoptedStyleSheets.push( stylesheet );
}

The imported stylesheet is a CSSOM CSSStyleSheet object and I can add it to the document using another CSSOM API.

So, if we don't mind using experimental non-standard Chrome-only API, loading styles as ES modules is possible!

How to load dependencies and inline scripts? A WordPress script is registered like:

wp_register_script( 'my-script', './my-script.js', [ 'dep1', 'dep2' ] );
wp_add_inline_script( 'my-script', 'window.__experimentalEnableFoo = true', 'before' );

When generating an ESM importmap from such a registration, we can easily map the handle to the src URL:

"my-script": "./my-script.js"

but what about the dependencies and the inline script?

There are two ways how to approach this. The first is not to use ESM importmaps, but a custom loader, and the "importmap" would contain the serialized script info:

"my-script": {
  src: './my-script.js',
  deps: [ 'dep1', 'dep2' ],
  before: [ 'window.__experimentalEnableFoo = true' ]
}

The loadScript function in the browser can use this info to fully and correctly load the my-script handle. There is a major problem with the inline scripts. In my example I'm serializing them in the importmap info, but if the scripts are big, it makes async loading pointless. An important case of inline scripts are localizations, and the localization data can be big. We wan't to load them async, too.

The second approach is to create a server-side endpoint for loading script handles, and use this endpoint's URLs to create the importmap:

"my-script": "/load-script-handle.php?handle=my-script"

The load-script-handle.php endpoint would act like a "mini-bundler", putting all the parts of the script together. Its response would be an ES module that looks like this:

// load the dependencies first
import 'dep1';
import 'dep2';

// the 'before' inline scripts
(function() {
  window.__experimentalEnableFoo = true;
})();

// the main script
(function() {
  // contents of my-script.js
})();

First it imports the dependencies, and then ships the sub-scripts wrapped inside IIFEs. Just like when webpack bundles individual modules into chunks.

The main problem I see here is that WordPress scripts can be registered differently on different route. The environment on a wp-admin/post.php page is different from a REST endpoint route and also different from a frontend page view. It's not entirely clear what /load-script-handle.php?handle=my-script means. On some routes the my-script script might not be registered at all, on other routes it might be registered, or configured (via inline script) differently. How to handle that?

For blocks this is probably not such a problem, because in practice they are always (?) registered in the universal init action, but as a general-purpose API, the load-script-handle.php endpoint needs to have a well-defined behavior, which it currently doesn't have.

To conclude, I think that yes, native ESM importmaps are desirable and can be implemented, but it's a lot of work, both in the prototype stage and even more work in the production stage. And the async block loading concept can be developed very well even without them.

[youknowriad]

How to load styles?

Is it also possible to load styles as JS (have a script registered in the import map that adds a <style> to the document). I think this can be a stop gap solution until CSS modules are adopted more globally.

How to load dependencies and inline scripts?

"my-script": "/load-script-handle.php?handle=my-script"

I'm fan of this approach but to be honest, I wouldn't care about inline scripts because they are a concept of existing WP scripts and there's no way for us to support backward compatibility for these because even if our loader supported inline scripts, we can't replicate the "context" in which the script loader executes today, so there's no way to produce 1-1 inline scripts. For this reason, I think there's no need to bother supporting inline scripts for es modules.

To conclude, I think that yes, native ESM importmaps are desirable and can be implemented, but it's a lot of work, both in the prototype stage and even more work in the production stage. And the async block loading concept can be developed very well even without them.

I think it's actually less work if we assume:

• styles are just JS modules that can be embedded within the actual ES package (inject the <script> and not register them as separate modules)
• no need to support inline scripts

Ideally, I also prefer if we don't introduce custom loaders (wrapper around import) and custom logic in the client to load these scripts because that adds a burden for us in terms of "forward compatibility". Implicitly, we're creating "special modules" and not embracing "esmodules" as such.

[jsnajdr]

I'm fan of this approach but to be honest, I wouldn't care about inline scripts because they are a concept of existing WP scripts

I don't agree here because inline scripts are a WordPress reality, a typical WordPress editor page is going to have 30 to 60 of them. And they are used to ship localization data for the scripts. And the async loader can support them, it's not terribly hard.

I'm trying to identify what are the breaking changes necessary to make async blocks work, and the set is not huge:

• blocks need to be more diligent about declaring stuff in block.json
• block icons can no longer be React code
• some selectors in the core/blocks and core/block-editor are now async, i.e., they initially return null, the start resolving, and after a while return the resolved result.
• some APIs in @wordpress/blocks are now async.
• transform functions on block transforms are now async.

Some of them will be very challenging to do with backward compatibility, we'll probably have to introduce v2 of some API, and calling a v1 of something will cause bailout from async loading. But the list is not long, and inline scripts are not on it.

and there's no way for us to support backward compatibility for these because even if our loader supported inline scripts, we can't replicate the "context" in which the script loader executes today

I don't see the issue here: inside a IIFE, the inline script runs pretty much in the same environment/context as before. this is the same global object, it has access to the same global variables...

[youknowriad]

I don't see the issue here: inside a IIFE, the inline script runs pretty much in the same environment/context as before. this is the same global object, it has access to the same global variables...

The issue is not in the frontend, it's when injecting the "inline script". For instance:

• the block editor adds "preloaded rest APIs" as an inline script to wp-api-fetch but these preloaded scripts are dependent on the "context". If we're loading "edit-post", there's a given list of preloaded apis, for "edit-site" another set, for most wp-admin pages, there are no preloaded scripts.

• In order to inject the correct inline scripts if wp-api-fetch is lazy-loaded, we'd need to pass the "context" to the loader which obviously defeats the purpose of the loader but also is impossible to do, because the "context" in which the inline scripts are added today can't be "serialized" in a URL.

That's just an example, plugins and core can use any random global from the current execution context of the inline script. So it's a lost battle anyway.

I'm trying to identify what are the breaking changes necessary to make async blocks work, and the set is not huge:

My opinion is that it's probably too much but I don't want this to be a blocker for experimentation, as you said, we need to push this further and see how to ship these changes iteratively without breakage. But I still think "block lazy loading" is more down the road and that we can do a lot already if we solve just "lazy loading" and implement it in places where we certain to not break anything (lazy load libraries..)

[jsnajdr]

the block editor adds "preloaded rest APIs" as an inline script to wp-api-fetch but these preloaded scripts are dependent on the "context".

I see what context you mean now. It's one case of the general issue I described above:

The main problem I see here is that WordPress scripts can be registered differently on different routes.

wp-api-fetch means different things on different routes, like edit-post vs edit-site. When loaded from a "central" endpoint like /load.php?handle=wp-api-fetch, it's not clear what to send.

we can do a lot already if we solve just "lazy loading" and implement it in places where we certain to not break anything

One approach that should be easily implementable: block.json declares an editorScript:

{
  "editorScript": "wp-block-image-editor"
}

which contains a browser-side registerBlockType registration call, but the edit component is lazy:

// wp-block-image-editor
const Edit = React.lazy( () => import( 'wp-block-image-editor-edit' ) );
registerBlockType( {
  name: 'core/image',
  icon: <svg>...</svg>,
  edit: Edit,
} );

This script is enqueued synchronously on the editor page, has no dependencies, and is therefore small. The real editing complexity is in the wp-block-image-editor-edit script. It can depend on all the big component libraries that some plugins ship etc.

Seems super-obvious now, and yet I rejected it 2 months ago when I started learning about block loading. I was probably too confused about the meaning of editorScript.

[tyxla]

Thanks, everyone for providing feedback here so far - it's been particularly beneficial!

I think it would be instrumental to get some feedback and thoughts from the @WordPress/performance folks.

[eclarke1]

Thanks @annezazu for looping in the Performance folks! I'd love to also bring in @felixarntz and @joemcgill here to review please (however noting they are away this week at WCUS).

[westonruter]

Just wanted to make clear for anyone confused what "async" means here. In this context, async here refers to dynamic loading of block editor scripts, not utilizing the async loading strategy which was introduced in WordPress 6.3. Should this discussion perhaps be re-titled "Dynamic block loading" to prevent confusion?

[gziolo]

I agree that "lazy loading" is a good fit. I went through comments in the issue #2768 created 6 years ago and it seems to be commonly used term by folks. What stands out is that React has the same term baked into their API: React.lazy. I also checked the webpack documentation and they have a guide about Lazy Loading. I would be in favor of changing the title in both places to replace async with lazy.

[jsnajdr]

So, would it be "lazy block loading", "lazy loading blocks" or "blocks lazy loading"? Many permutations are possible, which one sounds the best? 🙂

[westonruter]

I like "block lazy loading"

[gziolo]

I updated the title with better phrasing.

[tyxla]

Agreed that "lazy loading" and "block lazy loading" are better alternatives and will likely be more comprehensible terms for the global developer community.