Create Block: Improve custom project template configuration (#39049)

* Create Block: Improve project template configuration

* Update the tutorial for block creation

* Create Block: Improve documentation

bin/test-create-block.sh

@@ -20,14 +20,47 @@ error () {
 }
 
 cleanup() {
-	rm -rf "$DIRECTORY/esnext-test"
+	rm -rf "$DIRECTORY/example-static-es5"
+	rm -rf "$DIRECTORY/example-static"
 }
 
 trap cleanup EXIT
 
-status "Scaffolding block..."
-npx wp-create-block esnext-test --no-wp-scripts
-cd esnext-test
+# First test block
+
+status "Scaffolding Example Static (ES5) block..."
+npx wp-create-block example-static-es5 -t es5
+cd example-static-es5
+
+status "Verifying project..."
+expected=8
+actual=$( find . -maxdepth 1 -type f | wc -l )
+if [ "$expected" -ne "$actual" ]; then
+	error "Expected $expected files in the project root, but found $actual."
+    exit 1
+fi
+
+cd ..
+
+# Second test block
+
+status "Scaffolding Example Static block..."
+npx wp-create-block example-static --no-wp-scripts
+cd example-static
+
+status "Verifying project..."
+expected=5
+actual=$( find . -maxdepth 1 -type f | wc -l )
+if [ "$expected" -ne "$actual" ]; then
+	error "Expected $expected files in the project root, but found $actual."
+    exit 1
+fi
+expected=6
+actual=$( find src -maxdepth 1 -type f | wc -l )
+if [ "$expected" -ne "$actual" ]; then
+	error "Expected $expected files in the `src` directory, but found $actual."
+    exit 1
+fi
 
 status "Formatting files..."
 ../node_modules/.bin/wp-scripts format
@@ -37,9 +70,9 @@ status "Building block..."
 
 status "Verifying build..."
 expected=5
-actual=$( ls build | wc -l )
+actual=$( find build -maxdepth 1 -type f | wc -l )
 if [ "$expected" -ne "$actual" ]; then
-	error "Expected $expected files in the build folder, but found $actual."
+	error "Expected $expected files in the `build` directory, but found $actual."
     exit 1
 fi
 

docs/getting-started/create-block/README.md

@@ -15,10 +15,10 @@ The `@wordpress/create-block` package exists to create the necessary block scaff
 From your plugins directory, to create your block run:
 
 ```sh
-npx @wordpress/create-block gutenpride
+npx @wordpress/create-block gutenpride --template @wordpress/create-block-tutorial-template
 ```
 
-The [npx command](https://docs.npmjs.com/cli/v7/commands/npx) runs a command from a remote package, in this case our create-block package that will create a new directory called `gutenpride`, installs the necessary files, and builds the block plugin. If you want an interactive mode that prompts you for details, run the command without the `gutenpride` name.
+The [npx command](https://docs.npmjs.com/cli/v8/commands/npx) runs a command from a remote package, in this case our create-block package that will create a new directory called `gutenpride`, installs the necessary files, and builds the block plugin. If you want an interactive mode that prompts you for details, run the command without the `gutenpride` name.
 
 You now need to activate the plugin from inside wp-admin plugins page.
 

docs/getting-started/create-block/attributes.md

@@ -73,15 +73,15 @@ export default function Edit( { attributes, setAttributes } ) {
 **save.js** file:
 
 ```jsx
-import { __ } from '@wordpress/i18n';
 import { useBlockProps } from '@wordpress/block-editor';
 
 export default function save( { attributes } ) {
-	return <div { ...useBlockProps.save() }>{ attributes.message }</div>;
+	const blockProps = useBlockProps.save();
+	return <div { ...blockProps }>{ attributes.message }</div>;
 }
 ```
 
-If you have previously run `npm start`, and the script is still running, you can reload the editor now and add the block to test.
+If you have previously run `npm run start`, and the script is still running, you can reload the editor now and add the block to test.
 Otherwise rebuild the block using `npm run build`, reload the editor and add the block. Type a message in the editor, save, and view it in the post.
 
 Next Section: [Code Implementation](/docs/getting-started/create-block/block-code.md)

docs/getting-started/create-block/author-experience.md

@@ -125,15 +125,16 @@ Update `src/editor.scss` to:
 The edit function can simply be:
 
 ```jsx
-import { useBlockProps } from '@wordpress/block-editor';
 import { TextControl } from '@wordpress/components';
+import { useBlockProps } from '@wordpress/block-editor';
 
 import './editor.scss';
 
 export default function Edit( { attributes, setAttributes } ) {
+	const blockProps = useBlockProps();
 	return (
 		<TextControl
-			{ ...useBlockProps() }
+			{ ...blockProps }
 			value={ attributes.message }
 			onChange={ ( val ) => setAttributes( { message: val } ) }
 		/>

docs/getting-started/create-block/block-anatomy.md

@@ -17,7 +17,6 @@ import Edit from './edit';
 import save from './save';
 
 registerBlockType( 'create-block/gutenpride', {
-	apiVersion: 2,
 	/**
 	 * @see ./edit.js
 	 */
@@ -43,19 +42,21 @@ Most of the properties are set in the `block.json` file.
 
 ```json
 {
+	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
 	"name": "create-block/gutenpride",
+	"version": "0.1.0",
 	"title": "Gutenpride",
-	"category": "widgets",
-	"icon": "smiley",
-	"description": "Example block written with ESNext standard and JSX support – build step required.",
+	"category": "text",
+	"icon": "flag",
+	"description": "A Gutenberg block to show your pride! This block enables you to type text and style it with the color font Gilbert from Type with Pride.",
 	"supports": {
 		"html": false
 	},
 	"textdomain": "gutenpride",
-	"editorScript": "file:./build/index.js",
-	"editorStyle": "file:./build/index.css",
-	"style": "file:./build/style-index.css"
+	"editorScript": "file:./index.js",
+	"editorStyle": "file:./index.css",
+	"style": "file:./style-index.css"
 }
 ```
 

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

@@ -6,7 +6,7 @@ Note: The color may not work with all browsers until they support the proper col
 
 ## Load Font File
 
-Download and extract the font from the Type with Pride site, and copy it in the `src` directory of your plugin naming it `gilbert-color.otf`. To load the font file, we need to add CSS using standard WordPress enqueue, [see Including CSS & JavaScript documentation](https://developer.wordpress.org/themes/basics/including-css-javascript/).
+Download and extract the font from the Type with Pride site, and copy it in the `assets` directory of your plugin naming it `gilbert-color.otf`. To load the font file, we need to add CSS using standard WordPress enqueue, [see Including CSS & JavaScript documentation](https://developer.wordpress.org/themes/basics/including-css-javascript/).
 
 In the `gutenpride.php` file, the enqueue process is already setup from the generated script, so `index.css` and `style-index.css` files are loaded using:
 
@@ -31,12 +31,12 @@ Note: the block classname is prefixed with `wp-block`. The `create-block/gutenpr
 ```scss
 @font-face {
 	font-family: Gilbert;
-	src: url( gilbert-color.otf );
-	font-weight: bold;
+	src: url( ../assets/gilbert-color.otf );
+	font-weight: 700;
 }
 
 .wp-block-create-block-gutenpride {
-	font-family: Gilbert;
+	font-family: Gilbert, sans-serif;
 	font-size: 64px;
 }
 ```

docs/getting-started/create-block/finishing.md

@@ -23,3 +23,5 @@ Nested blocks, a block that contains additional blocks, is a common pattern used
 One of the best sources for information and reference is the Block Editor itself, all the core blocks are built the same way. A good way to learn how things are done is to find a core block code that does something close to what you are interested in and then using the same approach for your own block.
 
 All core blocks source are in the [block library package on GitHub](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src).
+
+Next Section: [Share your Block with the World](/docs/getting-started/create-block/submitting-to-block-directory.md)

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

@@ -29,15 +29,17 @@ The main plugin file created is the PHP file `gutenpride.php`, at the top of thi
 
 ```php
 /**
- * Plugin Name:     Gutenpride
- * Description:     Example block
- * Version:         0.1.0
- * Author:          The WordPress Contributors
- * License:         GPL-2.0-or-later
- * License URI:     https://www.gnu.org/licenses/gpl-2.0.html
- * Text Domain:     gutenpride
+ * Plugin Name:       Gutenpride
+ * Description:       Example static block scaffolded with Create Block tool.
+ * Requires at least: 5.8
+ * Requires PHP:      7.0
+ * Version:           0.1.0
+ * Author:            The WordPress Contributors
+ * License:           GPL-2.0-or-later
+ * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
+ * Text Domain:       gutenpride
  *
- * @package         create-block
+ * @package           create-block
  */
 ```
 
@@ -78,7 +80,7 @@ In `package.json`, there is a `scripts` property that defines what command to ru
   },
 ```
 
-These scripts are run by using: `npm run build` or `npm run start`
+These scripts are run by using: `npm run build` or `npm run start`.
 
 Use `npm run build` for running once to create a "production" build. This compresses the code down so it downloads faster, but makes it harder to read using browser tools—good for final deployment but not while developing.
 
@@ -92,32 +94,34 @@ 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( __DIR__ );
+	register_block_type( __DIR__ . '/build' );
 }
 add_action( 'init', 'create_block_gutenpride_block_init' );
 ```
 
-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.
+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 `build/block.json` file with the `editorScript` field. So now when the editor loads it will load this script. The source metadata file `src/block.json` is copied during the build process:
 
 ```json
 {
+	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
 	"name": "create-block/gutenpride",
+	"version": "0.1.0",
 	"title": "Gutenpride",
 	"category": "widgets",
 	"icon": "smiley",
-	"description": "Example block written with ESNext standard and JSX support – build step required.",
+	"description": "Example static block scaffolded with Create Block tool.",
 	"supports": {
 		"html": false
 	},
 	"textdomain": "gutenpride",
-	"editorScript": "file:./build/index.js",
-	"editorStyle": "file:./build/index.css",
-	"style": "file:./build/style-index.css"
+	"editorScript": "file:./index.js",
+	"editorStyle": "file:./index.css",
+	"style": "file:./style-index.css"
 }
 ```
 
-For the `editorScript` provided in the block metadata, the build process creates a secondary asset file that contains the list of dependencies and a file version based on the timestamp, this is the `index.asset.php` file.
+For the `editorScript` provided in the block metadata, the build process creates a secondary asset file that contains the list of dependencies and a file version based on the timestamp, this is the `build/index.asset.php` file.
 
 The `wp_register_script` function used internally registers a name, called the handle, and relates that name to the script file. The dependencies are used to specify if the script requires including other libraries. The version is specified so the browser will reload if the file changed.
 

docs/getting-started/devenv/README.md

@@ -17,7 +17,7 @@ Here is a summary of the guide. See each section for additional details and expl
 Download and install [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm)
 
 ```
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
 ```
 
 Quit and restart terminal
@@ -64,7 +64,7 @@ Here are the quick instructions to install using nvm, see the [full installation
 Run the following on the command-line to install nvm:
 
 ```sh
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
 ```
 
 Note: On macOS, the required developer tools are not installed by default, if not already installed you may be prompted to download the install.
@@ -100,10 +100,10 @@ The important part after installing is being able to use them in your terminal.
 
 ```sh
 > node -v
-v14.18.1
+v14.19.0
 
 > npm -v
-6.14.15
+6.14.16
 ```
 
 Your versions may not match exactly, that is fine. The minimum version for Node.js is >= 12 and for npm >= 6.9, using v14 will be supported until upgrade is required.
@@ -159,7 +159,7 @@ A common issue when running `wp-env` is `Error while running docker-compose comm
 If you see the error: `Host is already in use by another container`
 
 -   The container is already running, or another one is. You can stop an existing container running use `wp-env stop` from the directory you started it.
-- If you do not remember the directory you started wp-env in, you can stop all containers with `docker stop $(docker ps -q)`. Please note, this will stop all containers, use caution with this command.
+-   If you do not remember the directory you started wp-env in, you can stop all containers with `docker stop $(docker ps -q)`. Please note, this will stop all containers, use caution with this command.
 
 ### Alternative to Docker
 

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

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Breaking Change
+
+-   Bring project's template compatibility with `@wordpress/create-block` v3 ([#39049](https://github.com/WordPress/gutenberg/pull/39049)).
+
+### Enhancement
+
+-   Update project template configuration and templates to synchronize with the updated [Create a Block Tutorial](https://developer.wordpress.org/block-editor/getting-started/create-block/) ([#39049](https://github.com/WordPress/gutenberg/pull/39049)).
+
 ## 1.4.0 (2022-01-27)
 
 ### Enhancement

packages/create-block-tutorial-template/templates/src/edit.js.mustache → packages/create-block-tutorial-template/block-templates/edit.js.mustache

@@ -28,11 +28,10 @@ import { useBlockProps } from '@wordpress/block-editor';
 export default function Edit( { attributes, setAttributes } ) {
 	const blockProps = useBlockProps();
 	return (
-		<div { ...blockProps }>
-			<TextControl
-				value={ attributes.message }
-				onChange={ ( val ) => setAttributes( { message: val } ) }
-			/>
-		</div>
+		<TextControl
+			{ ...blockProps }
+			value={ attributes.message }
+			onChange={ ( val ) => setAttributes( { message: val } ) }
+		/>
 	);
 }

packages/create-block-tutorial-template/block-templates/editor.scss.mustache

@@ -0,0 +1,13 @@
+/**
+ * The following styles get applied inside the editor only.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-{{namespace}}-{{slug}} input[type='text'] {
+	font-family: Gilbert;
+	font-size: 64px;
+	color: inherit;
+	background: inherit;
+	border: 0;
+}

packages/create-block-tutorial-template/templates/src/index.js.mustache → packages/create-block-tutorial-template/block-templates/index.js.mustache

@@ -36,12 +36,10 @@ registerBlockType( '{{namespace}}/{{slug}}', {
 			message: '{{title}}',
 		},
 	},
-
 	/**
 	 * @see ./edit.js
 	 */
 	edit: Edit,
-
 	/**
 	 * @see ./save.js
 	 */

packages/create-block-tutorial-template/index.js

@@ -6,7 +6,6 @@ const { join } = require( 'path' );
 module.exports = {
 	defaultValues: {
 		slug: 'gutenpride',
-		namespace: 'create-block-tutorial',
 		category: 'text',
 		title: 'Gutenpride',
 		description:
@@ -23,6 +22,7 @@ module.exports = {
 			html: false,
 		},
 	},
-	templatesPath: join( __dirname, 'templates' ),
+	pluginTemplatesPath: join( __dirname, 'plugin-templates' ),
+	blockTemplatesPath: join( __dirname, 'block-templates' ),
 	assetsPath: join( __dirname, 'assets' ),
 };