Packages: New create-block package for block scaffolding

[gziolo]

Description

Closes #10629.

Create Block is proposed to be an officially supported way to create blocks for registering
a block for a WordPress plugin. It offers a modern build setup with no
configuration. It generates PHP, JS, CSS code, and everything else you need to start the project.

It is largely inspired by create-react-app.
Major kudos to @gaearon, the whole Facebook team,
and the React community.

Another way of making a developer’s life easier is to use WP-CLI,
which provides a command-line interface for many actions you might perform on
the WordPress instance. One of the commands wp scaffold block was used as
the baseline for this tool and ES5 template in particular.

The difference between wp scaffold block and this new package is that it scaffold ESNext template by default and bootstraps everything that is necessary to maintain modern JavaScript tooling in the project.

All this work can be tested also on npm using https://www.npmjs.com/package/create-wordpress-block that was created to validate the idea, test publishing workflow and collect the initial feedback

Usage

The following command generates PHP, JS and CSS code for registering a block.

$ npm init @wordpress/block [options] [slug]

[slug] is optional. When provided it triggers the quick mode where it is used
as the block slug used for its identification, the output location for scaffolded files,
and the name of the WordPress plugin. The rest of the configuration is set to all
default values.

Options:

-t, --template <name>  template type name, allowed values: "es5", "esnext" (default: "esnext")
-V, --version          output the version number
-h, --help             output usage information

More examples:

1. Interactive mode - it gives a chance to customize a few most important options
   before the code gets generated.

$ npm init @wordpress/block

2. ES5 template – it is also possible to pick ES5 template when you don't want
   to deal with a build step (npm start) which enables ESNext and JSX support.

$ npm init @wordpress/block --template es5

3. Help – you need to use npx to output usage information.

$ npx @wordpress/create-block --help

When you scaffold a block, you must provide at least a slug name, the namespace
which usually corresponds to either the theme or plugin name, and the category.
In most cases, we recommended pairing blocks with plugins rather than themes,
because only using plugin ensures that all blocks still work when your theme changes.

Available Commands

Inside that bootstrapped directory (it doesn't apply to es5 template), you
can run several commands:

$ npm start

Starts the build for development. Learn more.

$ npm run build

Builds the code for production. Learn more.

$ npm run lint:css

Lints CSS files. Learn more.

$ npm run lint:js

Lints JavaScript files. Learn more.

$ npm run packages-update

Updates WordPress packages to the latest version. Learn more.

How has this been tested?

This package is still not published to npm out of the obvious reasons, so the temporary way to test it looks as follows:

npx wp-create-block --help

npx wp-create-block --version

npx wp-create-block - to see full interactive mode (npm install during the process takes some time)

npx wp-create-block my-quick-block - to see quick mode

npx wp-create-block --template es5 - to scaffold ES5 template

Types of changes

New package.

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR. .

[ItsJonQ]

@gziolo I just tested it and it's working as advertised!

Works, out of the box, when generated into a WordPress plugins directly.
npm start automatically watches/rebuilds.

CSS-aside, the workflow feels identical to that of create-guten-block 🙌 .

---

Import awesomeness

It's a tiny detail, but I really have to commend you for leveraging wp-scripts for the start/build scripts. From a Gutenberg project dev perspective, this choice seems obvious.

However, for a block plugin author dev perspective, this means that I can use import for Gutenberg packages, for example:

import { Button } from '@wordpress/components';

Rather than from the global (window) namespace:

const { Button } = wp.components

CSS (Question)

I noticed that the .css files were outside of the src/ directory. Based on my experiences with projects like create-react-app, I expected (almost) everything to be there. Is this something we're planning to do in the future?

(Open question! I'm not disagreeing with the current implementation)

---

Thanks again for your efforts! You've created the foundations for something really special for the Gutenberg project IMO ❤️

[gziolo]

I noticed that the .css files were outside of the src/ directory. Based on my experiences with projects like create-react-app, I expected (almost) everything to be there. Is this something we're planning to do in the future?

(Open question! I'm not disagreeing with the current implementation)

I fully agree that it isn't the best experience with regard to CSS. The majority of custom configurations for WordPress development I've seen so far allow CSS import statements. I think we should follow the same approach and finally implement #14801. I'm wondering if we could add something similar to what is used for the Storybook:

gutenberg/storybook/webpack.config.js

Lines 12 to 29 in 26062c8

	test: /\.scss$/,
	use: [
	'style-loader',
	'css-loader',
	/**
	* Configuring PostCSS with Webpack
	* https://github.com/postcss/postcss-loader#plugins
	*/
	{
	loader: 'postcss-loader',
	options: {
	ident: 'postcss',
	plugins: () => postCssConfigPlugins,
	},
	},
	'sass-loader',
	],
	include: path.resolve( __dirname ),

I went with static files for the time being. The package is at the moment versioned 0.5.1 which reflects its current status.

Nice to have features for v1.0.0 would be:

• native support for CSS imports (Adding SASS / PostCSS build process to wp-scripts package #14801)
• readme.txt file template included for the plugin (Feature: Add template which would support WordPress single block directory gziolo/create-wordpress-block#1)
• a script to generate the zip file for the plugin so authors could have an easy workflow for distribution (Scripts: Add new command which generates zip file for the plugin #19237)

[gziolo]

Props to @aduth for the tip about making action async in the commander setup, code changes 260345b.

[gziolo]

Thanks @aduth for you feedback. I really appreciate all the comments. I will merge this PR as is and open a follow-up according to the comments I left to make the process simpler.

[gziolo]

I started #19867 which partially addresses feedback shared. I will continue to work on Monday.

[youknowriad]

This is cool.

[strarsis]

@gziolo:

/home/build/.npm/_npx/13386/lib/node_modules/@wordpress/create-block/lib/scaffold.js:6
const { readFile, writeFile } = require( 'fs' ).promises;
        ^

TypeError: Cannot destructure property `readFile` of 'undefined' or 'null'.

with npm init @wordpress/block on node v8.14.0 (LTS),
npm 6.13.7 and WSL 1 Ubuntu (stable) (Bash on Windows).

[gziolo]

Node 10.0.0+ is required, see:
https://github.com/WordPress/gutenberg/tree/master/packages/create-block#quick-start

(requires node version 10.0.0 or above, and npm version 6.1.0 or above)

I'll open an issue to add version checking in the script. Promises API for fs was added in Node 10.x.

Aside: Node 8.x is no longer maintained. See: https://github.com/nodejs/Release#release-schedule

[gziolo]

@strarsis – opened #20142 to track the issue you raised.

[devinsays]

Thanks for the great tool! I've been testing it out with a new block.

One issue I just ran across that I assume some other people may have is:
Support for the experimental syntax 'classProperties' isn't currently enabled

I believe I've fixed it by running:
npm install @babel/plugin-proposal-class-properties --save-dev

And then adding this at the bottom of my package.json:

	"babel": {
		"presets": [
			"@wordpress/default"
		],
		"plugins": [
			"@babel/plugin-proposal-class-properties"
		]
	}

If this is the incorrect approach, please let me know!

[gziolo]

One issue I just ran across that I assume some other people may have is:
Support for the experimental syntax 'classProperties' isn't currently enabled

Correct. It's all by design. While it's fine to experiment in general, in WordPress core we make our best to use only those features that are standardized. That's why in the case of Babel we use only features that are part of ESNext standard or were accepted to be added in the next revision. The only exception is JSX.

I believe I've fixed it by running:
npm install @babel/plugin-proposal-class-properties --save-dev

And then adding this at the bottom of my package.json:

	"babel": {
		"presets": [
			"@wordpress/default"
		],
		"plugins": [
			"@babel/plugin-proposal-class-properties"
		]
	}

If this is the incorrect approach, please let me know!

Yes, it's all good. For reference, you can check how we override it in Gutenberg:

gutenberg/babel.config.js

Lines 1 to 8 in 59b07cc

	module.exports = function( api ) {
	api.cache( true );
	return {
	presets: [ '@wordpress/babel-preset-default' ],
	plugins: [ 'babel-plugin-emotion', 'babel-plugin-inline-json-import' ],
	};
	};

[AndreaBarghigiani]

Hi @gziolo and @devinsays sorry to bother you but I am new to React, Webpack and Gutenberg and I do not understand why it is enough to simply add the Babel configuration to the package.json file.

I thought I should extend the webpack.config.js as suggested here because from the course about Gutenberg development that I am following the developer adds the plugin right inside the file and does not mention the edits in package.json.

In order to do so, I tried the following code but it didn't work:

const defaultConfig = require("@wordpress/scripts/config/webpack.config");

module.exports = {
	...defaultConfig,
	module: {
		...defaultConfig.module,
		rules: [
			...defaultConfig.module.rules,
			{
				test: /\.js$/,
				exclude: /node_modules/,
				use: [
					{
						options: {
							plugins: ["@babel/plugin-proposal-class-properties"]
						}
					}
				]
			}
		]
	}
};

Would you be so kind as to let me understand what am I missing? Even a simple link to documentation will be incredibly useful.

Thank you in advance.

BTW the solution proposed by @devinsays works great but I am trying to understand where I got wrong.

[mtias]

This is great @gziolo, nice work. It'd also give us a way to promote best practices — such as loading block assets only when a block is used on the front-end. (#5445)

[gziolo]

This is great @gziolo, nice work. It'd also give us a way to promote best practices — such as loading block assets only when a block is used on the front-end. (#5445)

I'm sure that once Block Directory is up and running we are in the position to add further improvements like the one you highlighted. The biggest benefit of having this scaffolding tool that we can easily change the templates to make it work out of the box.

[gziolo]

Would you be so kind as to let me understand what am I missing? Even a simple link to documentation will be incredibly useful.

Thank you in advance.

BTW the solution proposed by @devinsays works great but I am trying to understand where I got wrong.

@AndreaBarghigiani, what @devinsays works perfectly fine because of this condition in the default webpack config:

gutenberg/packages/scripts/config/webpack.config.js

Lines 51 to 61 in b0dbaa1

	// Provide a fallback configuration if there's not
	// one explicitly available in the project.
	...( ! hasBabelConfig() && {
	babelrc: false,
	configFile: false,
	presets: [
	require.resolve(
	'@wordpress/babel-preset-default'
	),
	],
	} ),

As far as I follow, your proposal adds another rule for JavaScript files but you would have to validate which one takes precedence, the one that already exists or the newly added one. Anyway, even when your rule triggers, it contains only the plugin modified without any presets.

In general, if you want to have a custom Babel config, it's better to set it for the whole project because of other tools that might want to use those custom features as well.

[niklasp]

So how can I add scss compilation to the build process easily. I did include a custom webpack.config.js with the content:

const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
const path = require( 'path' );

module.exports = {
    ...defaultConfig,
		entry: {
			index: path.resolve( process.cwd(), 'src', 'index.js' ),
			editor: path.resolve( process.cwd(), 'src', 'editor.scss' ),
			style: path.resolve( process.cwd(), 'src', 'style.scss' ),
		},
    module: {
        ...defaultConfig.module,
        rules: [
            ...defaultConfig.module.rules,
        ]
    }
};

This works, but I guess it is not the way to do it, as it creates, alongside build/editor.css and build/style.css, also the files editor.js, editor.asset.php style.js, style.asset.php`.

[gziolo]

@niklasp, with the last release of @wordpress/scripts it's now possible to use import statement for CSS files in JavaScript code to let webpack do its job. It's implemented a bit different than the setup you shared but it should work the very similar, see more at https://www.npmjs.com/package/@wordpress/scripts#using-css.