Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Blocks without asset.php file cannot be registered #40447

Closed
kmonahan opened this issue Apr 19, 2022 · 15 comments
Closed

Blocks without asset.php file cannot be registered #40447

kmonahan opened this issue Apr 19, 2022 · 15 comments
Labels
Developer Experience Ideas about improving block and theme developer experience [Feature] Block API API that allows to express the block paradigm. [Type] Developer Documentation Documentation for developers

Comments

@kmonahan
Copy link

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

@gziolo gziolo added [Type] Developer Documentation Documentation for developers Developer Experience Ideas about improving block and theme developer experience [Feature] Block API API that allows to express the block paradigm. labels Apr 19, 2022
@jg314
Copy link
Contributor

jg314 commented Apr 21, 2022

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
Copy link
Member

gziolo commented Apr 30, 2022

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
Copy link

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
Copy link
Member

gziolo commented May 6, 2022

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
Copy link
Contributor

strarsis commented May 11, 2022

+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...

@gziolo gziolo mentioned this issue May 23, 2022
69 tasks
@Inclushe
Copy link

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

@strarsis
Copy link
Contributor

strarsis commented May 26, 2022

@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
Copy link
Contributor

@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
Copy link
Contributor

strarsis commented May 27, 2022

@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
Copy link
Author

@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
Copy link

@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.

tharsheblows added a commit to tharsheblows/gutenberg that referenced this issue Jun 2, 2022
There was a missing step in the plain javascript documentation which missed out adding the asset file. Issue WordPress#40447
ryanwelcher pushed a commit that referenced this issue Jun 2, 2022
There was a missing step in the plain javascript documentation which missed out adding the asset file. Issue #40447
@annezazu
Copy link
Contributor

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

@lime
Copy link

lime commented Jan 12, 2023

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
Copy link

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
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Developer Experience Ideas about improving block and theme developer experience [Feature] Block API API that allows to express the block paradigm. [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

No branches or pull requests