Some block.json minutia

I spent some time today updating an older block plugin to use block.json and used that opportunity to take a closer look at what block.json provides and how it enqueues scripts and styles. I have a better grasp of what to expect as a result.

I started with the metadata example in the WordPress block editor documentation as well as Elaine’s nice write-up on our site.

If style is the path of a filename, and the stylesheet is less than 20kb, there is a good chance it will be output inline in the HEAD of the document. If it is larger than 20kb, it will be enqueued with the WordPress version number appended to its URL.

If style is the handle of a registered stylesheet, it will be output as originally registered. This allows you to declare a version number.

It is possible to filter this 20000 character limit via styles_inline_size_limit so that the file is more likely to be enqueued.

If script is the path of a filename, it will be enqueued in the HEAD of the document.

If script is the handle of a registered script, it will be output as originally registered. The version number is pulled from the script’s asset PHP file in both cases.

The script specified for script will be used on the front end and in the editor. 

In WordPress 5.8, it may be possible to work around this by only registering the script handle if ( ! is_admin() ), but I’d treat that as a hacky workaround for now.

In WordPress 5.9, a viewScript argument will be supported that will only enqueue the script on the front end.

This seems a bit quirky for back-compat. If I write a plugin for 5.8, I’ll probably have to stick with script until I’m sure users have updated to 5.9. I don’t think we can do easy version/feature checking with block.json the same way we can in PHP.

There is an apiVersion argument that could be changed, though I have not yet found a discussion covering the expectations around that number. It does seem more applicable to the APIs the block is expecting to be available in Gutenberg rather than the version of the metadata schema itself.

I opened WP trac ticket 54018 several months ago to request additional arguments to dictate where a script should load. Maybe I should open that in the Gutenberg repository instead. (Are block.json schema updates discussed as part of core or a feature plugin?)

I’m also now watching Gutenberg ticket 33542, which is tracking some additional changes to asset handling. 💯 for some of those updates.