Block API: Apply enhancements included in WordPress 5.8

See https://make.wordpress.org/core/2021/06/23/block-api-enhancements-in-wordpress-5-8/.

docs/getting-started/tutorials/create-block/block-code.md

@@ -12,7 +12,7 @@ In the `gutenpride.php` file, the enqueue process is already setup from the gene
 
 ```php
 function create_block_gutenpride_block_init() {
-	register_block_type_from_metadata( __DIR__ );
+	register_block_type( __DIR__ );
 }
 add_action( 'init', 'create_block_gutenpride_block_init' );
 ```

docs/getting-started/tutorials/create-block/wp-plugin.md

@@ -92,12 +92,12 @@ To load the built script, so it is run within the editor, you need to tell WordP
 
 ```php
 function create_block_gutenpride_block_init() {
-	register_block_type_from_metadata( __DIR__ );
+	register_block_type( __DIR__ );
 }
 add_action( 'init', 'create_block_gutenpride_block_init' );
 ```
 
-The `register_block_type_from_metadata` function registers the block we are going to create and specifies the `editor_script` file handle registered from the metadata provided in `block.json` file. So now when the editor loads it will load this script.
+The `register_block_type` function registers the block we are going to create and specifies the editor script handle registered from the metadata provided in `block.json` file with the `editorScript` field. So now when the editor loads it will load this script.
 
 ```json
 {
@@ -137,6 +137,6 @@ For more info, see the build section of the [Getting Started with JavaScript tut
 
 ## Summary
 
-Hopefully, at this point, you have your plugin created and activated. We have the package.json with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor.
+Hopefully, at this point, you have your plugin created and activated. We have the `package.json` with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor.
 
 Next Section: [Anatomy of a Block](/docs/getting-started/tutorials/create-block/block-anatomy.md)

docs/reference-guides/block-api/block-metadata.md

@@ -1,11 +1,6 @@
 # Metadata
 
-To register a new block type using metadata that can be shared between codebase that uses JavaScript and PHP, start by creating a `block.json` file. This file:
-
--   Gives a name to the block type.
--   Defines some important metadata about the registered block type (title, category, icon, description, keywords).
--   Defines the attributes of the block type.
--   Registers all the scripts and styles for your block type.
+Starting in WordPress 5.8 release, we encourage using the `block.json` metadata file as the canonical way to register block types. Here is an example `block.json` file that would define the metadata for a plugin create a notice block.
 
 **Example:**
 
@@ -50,9 +45,19 @@ To register a new block type using metadata that can be shared between codebase
 }
 ```
 
-The same file is also used when [submitting block to Block Directory](/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md).
+## Benefits using the metadata file
+
+The block definition allows code sharing between JavaScript, PHP, and other languages when processing block types stored as JSON, and registering blocks with the `block.json` metadata file provides multiple benefits on top of it.
+
+From a performance perspective, when themes support lazy loading assets, blocks registered with `block.json` will have their asset enqueuing optimized out of the box. The frontend CSS and JavaScript assets listed in the `style` or `script` properties will only be enqueued when the block is present on the page, resulting in reduced page sizes.
+
+Furthermore, because the [Block Type REST API Endpoint](https://developer.wordpress.org/rest-api/reference/block-types/) can only list blocks registered on the server, registering blocks server-side is recommended; using the `block.json` file simplifies this registration.
+
+Last, but not least, the [WordPress Plugins Directory](https://wordpress.org/plugins/) can detect `block.json` files, highlight blocks included in plugins, and extract their metadata. If you wish to [submit your block(s) to the Block Directory](/docs/getting-started/tutorials/create-block/submitting-to-block-directory.md), all blocks contained in your plugin must have a `block.json` file for the Block Directory to recognize them.
 
-## Server-side registration
+## Block registration
+
+### PHP (server-side)
 
 The [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) function that aims to simplify the block type registration on the server, can read metadata stored in the `block.json` file.
 
@@ -75,6 +80,41 @@ register_block_type(
 );
 ```
 
+### JavaScript (client-side)
+
+When the block is registered on the server, you only need to register the client-side settings on the client using the same block’s name.
+
+**Example:**
+
+```js
+registerBlockType( 'my-plugin/notice', {
+	edit: Edit,
+	// ...other client-side settings
+} );
+```
+
+Although registering the block also on the server with PHP is still recommended for the reasons above, if you want to register it only client-side you can now use `registerBlockType` method from `@wordpress/blocks` package to register a block type using the metadata loaded from `block.json` file.
+
+The function takes two params:
+
+-   `$blockNameOrMetadata` (`string`|`Object`) – block type name (supported previously) or the metadata object loaded from the `block.json` file with a bundler (e.g., webpack) or a custom Babel plugin.
+-   `$settings` (`Object`) – client-side block settings.
+
+It returns the registered block type (`WPBlock`) on success or `undefined` on failure.
+
+**Example:**
+
+```js
+import { registerBlockType } from '@wordpress/blocks';
+import Edit from './edit';
+import metadata from './block.json';
+
+registerBlockType( metadata, {
+	edit: Edit,
+	// ...other client-side settings
+} );
+```
+
 ## Block API
 
 This section describes all the properties that can be added to the `block.json` file to define the behavior and metadata of block types.

docs/reference-guides/block-api/block-registration.md

@@ -2,7 +2,7 @@
 
 Block registration API reference.
 
-**Note:** You can use the functions documented on this page, but a flexible method to register new block types is to use the block.json metadata file. See [metadata documentation for complete information](/docs/reference-guides/block-api/block-metadata.md).
+**Note:** You can use the functions documented on this page to register a block on the client-side only, but a flexible method to register new block types is to use the `block.json` metadata file. See [metadata documentation for complete information](/docs/reference-guides/block-api/block-metadata.md).
 
 ## `registerBlockType`
 

packages/create-block-tutorial-template/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Enhancement
+
+-   Plugin scaffolded requires WordPress 5.8 now ([#33252](https://github.com/WordPress/gutenberg/pull/33252).
+-   Scaffolded block is now registered from `block.json` with the `register_block_type` helper ([#33252](https://github.com/WordPress/gutenberg/pull/33252)).
+
 ## 1.2.0 (2021-04-06)
 
 ### Enhancement

packages/create-block-tutorial-template/templates/$slug.php.mustache

@@ -4,7 +4,7 @@
 {{#description}}
  * Description:       {{description}}
 {{/description}}
- * Requires at least: 5.7
+ * Requires at least: 5.8
  * Requires PHP:      7.0
  * Version:           {{version}}
 {{#author}}
@@ -29,6 +29,6 @@
  * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
  */
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
-	register_block_type_from_metadata( __DIR__ );
+	register_block_type( __DIR__ );
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );

packages/create-block/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Enhancement
+
+-   Plugin scaffolded with the `esnext` template requires WordPress 5.8 now ([#33252](https://github.com/WordPress/gutenberg/pull/33252).
+-   Block scaffolded with the `esnext` template is now registered from `block.json` with the `register_block_type` helper ([#33252](https://github.com/WordPress/gutenberg/pull/33252)).
+
 ## 2.3.0 (2021-04-29)
 
 ### Enhancement

packages/create-block/lib/templates/esnext/$slug.php.mustache

@@ -4,7 +4,7 @@
 {{#description}}
  * Description:       {{description}}
 {{/description}}
- * Requires at least: 5.7
+ * Requires at least: 5.8
  * Requires PHP:      7.0
  * Version:           {{version}}
 {{#author}}
@@ -29,6 +29,6 @@
  * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
  */
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
-	register_block_type_from_metadata( __DIR__ );
+	register_block_type( __DIR__ );
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );