Blocks without asset.php file cannot be registered

[kmonahan]

Description

Blocks without an .asset.php file, such as the Hello, World block from the Building a Basic Block tutorial, result in a PHP notice during the registration process.

<?php
$script_asset_path = wp_normalize_path(
  realpath(
    dirname( $metadata['file'] ) . '/' .
    substr_replace( $script_path, '.asset.php', - strlen( '.js' ) )
  )
);

results in $script_asset_path being set to an empty string when no .asset.php file exists, triggering the _doing_it_wrong error.

If this is the intended behavior, the tutorial steps should probably be updated to include a step to manually create that file when the build tools aren't being used.

Step-by-step reproduction instructions

1. Follow the instructions at https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/writing-your-first-block-type/ to create a Hello World block, using the Plain JS options with no build process.
2. Observe that the block is not registered. Instead the error "Notice: register_block_script_handle was called incorrectly. The asset file for the "editorScript" defined in "gutenberg-examples/example-01-basic" block definition is missing." is displayed.
3. Add an empty block.asset.php file to the plugin directory.
4. Observe that the error goes away and the block can then be added in the editor.

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[jg314]

Thanks for creating this issue @kmonahan. I had been working on this for a few hours before realizing that the missing asset.php file was the issue.

We'd love to avoid building that file using @wordpress/scripts. Our team is using a custom Webpack implementation and are worried about long term confusion if we're using two different build approaches.

[gziolo]

We have a decent proposal to extend block.json capabilities for block assets summarized in this comment: #33542 (comment). The idea is to pass all the required information as an object when you don’t want to use the build step or when the default behavior is imperfect.

[AnupamKhosla]

Thanks a lot for bring this up, I was learning through the tutorial and couldn't figure out why the custom block is registered but doesn't show in the Gutenberg editor. I tried to debug:

function gutenberg_examples_01_register_block() {
    $res = register_block_type( __DIR__ "/myguten");
	var_dump($res);	
}
add_action( 'init', 'gutenberg_examples_01_register_block' );

The output gives a proper registered block which has bool(false) as it's editor_Script property. Then I did go into the rabbit hole of the actual wordpress source code and goto https://github.com/WordPress/wordpress-develop/blob/0ea7a38664746f9ad4f402768975c66928817531/src/wp-includes/blocks.php#L229 and from there went to https://github.com/WordPress/wordpress-develop/blob/0ea7a38664746f9ad4f402768975c66928817531/src/wp-includes/blocks.php#L75 and got to the exact point @kmonahan got:

https://github.com/WordPress/wordpress-develop/blob/0ea7a38664746f9ad4f402768975c66928817531/src/wp-includes/blocks.php#L89

But I couldn't understand this and then I installed the whole starter-block plugin and finally tada!!! index.asset.php file in the build folder.

Heck man, WordPress documentation should explicitly mention this.

[gziolo]

Heck man, WordPress documentation should explicitly mention this.

Yes, I see now where the confusion comes from. I’ll see how we could improve that.

[strarsis]

+1, had to walk through the code to find that there is a condition for the existence of such a index.asset.php before the block (editor) script is actually enqueued.
The documentation mentions that .asset.php file:

The definition is stored inside separate PHP file which ends with .asset.php and is located next to the JS/CSS file listed in block.json. WordPress will automatically detect this file through pattern matching. This option is the preferred one as it is expected it will become an option to auto-generate those asset files with @wordpress/scripts package.

Notably:

This option is the preferred one as it is expected it will become an option to auto-generate those asset files with @wordpress/scripts package.

Edit: I just updated to the latest @wordpress/scripts package and run the build and the index.asset.php was auto-generated.
So this part of the documentation is outdated I guess...

[Inclushe]

I encountered this issue going through the Create a basic block tutorial from the Block Editor Handbook. Not fun.

[strarsis]

@Inclushe: I updated to latest version of @wordpress/scripts and re-run the build script, with recent versions of @wordpress/scripts, the index.asset.php was auto-generated. Maybe this also helps in your case.

The documentation should mention this was added with more recent versions of @wordpress/scripts,
probably the example projects should also have their @wordpress/scripts dependency updated.

[ryanwelcher]

@kmonahan thanks for opening this issue and sorry for the frustrating experience! I think we can start by updating the tutorial to be more clear about the need for the index.asset.php. I'll start a PR for that

[strarsis]

@ryanwelcher: And I am right with the assumption/experience that updating @wordpress/scripts to latest version resolves the issue as the index.asset.php file is then automatically generated by the build script?
This should also be mentioned in the documentation (and the minimum version where this was introduced).

[kmonahan]

@strarsis The @wordpress/scripts tools do generate an index.asset.php file, but the issue is specifically when someone follows the Plain JS instructions in the tutorial and does not use the build script. Updating the tutorial sounds right to me.

[Inclushe]

@kmonahan The JSX example also does not work. I had to hack together my own basic Gutenberg block using Parcel, which can be found in this repo.

I have a use case where I would like to use this custom setup, and ideally @wordpress/scripts should not be the only way to develop Gutenberg blocks.

[annezazu]

@ryanwelcher can we close this based on #41511 being merged?

[lime]

Having gone through the same discovery process as others here, I would suggest tweaking the error message.

Function register_block_script_handle was called incorrectly.
The asset file for the "editorScript" defined in "foo-bar/test-block" block definition is missing.

"editorScript": "file:./block.js",

As a relative novice, I interpreted the message as meaning WP couldn't find my block.js file, and that something was wrong in how I was referencing it. It was only when I started writing this comment that I understood that WP was telling me what the problem was the whole time, since "asset file" here refers to the expected block.asset.php file.

Maybe the improvement could be as tiny as the following? At least in my case, it would have put me on the right track a lot sooner.

The .asset.php file for the "editorScript" defined in "foo-bar/test-block" block definition is missing.

[chris-monahan]

I found that when using plain webpack or just a custom webpack config for wp-scripts build then you also lose the index.asset.php file (as well as no longer recognising all of the core wp dependencies as externals, resulting in a huge bundle file).

In the end I found the solution by inspecting the default webpack config in node_modules/@wordpress/scripts/config and found the dependency extraction plugin.

It would be helpful if this was more clearly documented upfront that this is a pretty much hard requirement for any project building with plain webpack or a seperate custom webpack config.

[mburridge]

I'm closing this issue as it has been addressed by PR #41511. Feel free to request that it be re-opened if you feel that there is still an issue here.