Learn how to set up the development environment for WordPress’ React-based Gutenberg editor, as well has how to create a new project from scratch.

Gutenberg is the React-based WordPress editor. It comes in two versions: the Gutenberg plugin, which has a fast development cycle, churning out new features every two weeks; and the integration to WordPress core (called simply the WordPress editor), which consolidates the new features every three to four months.

Gutenberg is based on blocks, which are high-level components intended to provide a single piece of functionality accessible via the editor, currently to create content — but, in the not-so-distant future, to build the site, too. Blocks make it easy to save the content into the database and, being based in React, enable rich user interactions.

Since functionality is provided via plugins, WordPress has seen the emergence of plugins bundling several blocks together. However, since its latest release (version 8.4, from end of June 2020), Gutenberg integrates a block directory within the editor, which enables us to install a block on the fly while editing the blog post:

Block directory.

The block directory works with single-block plugins only. Hence, producing our plugins providing only one block improves the chances of its being installed by the user:

• Multi-block plugins: Installable through the plugin directory
• Single-block plugins: Installable through the plugin directory and the block directory

In this article, we will learn how to create a new project for single-block plugins and for multiple-block plugins, and how to set up the development environment effortlessly.

Scaffolding a single-block plugin

There are several tools to automate the process of setting up the project. These come with a predefined configuration that works for the majority of cases, and it can be customized for the exceptional cases, involving webpack (to bundle the JavaScript files for distribution), Babel (to compile modern JavaScript code into legacy code that can run in older browsers), ESLint (to analyze the JavaScript code), and a few others dependencies.

The available tools are:

• The WP CLI [scaffold](https://github.com/wp-cli/scaffold-command#wp-scaffold-block) command
• The [create-guten-block](https://github.com/ahmadawais/create-guten-block) package
• The [@wordpress/create-block](https://developer.wordpress.org/block-editor/packages/packages-create-block/) package

@wordpress/create-block is the official solution, maintained by the team developing Gutenberg. As such, we can expect that it will always be up to date with the project’s requirements. For instance, at the same time Gutenberg 8.4 was released, @wordpress/create-block was updated to generate the required metadata to support the block directory.

This tool is largely inspired by create-react-app: it is a Node.js process that leverages npm to install the required dependencies. To scaffold the new block, we execute in the command line:

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

The slug is the block slug used for identification, and it will also give the name to the plugin. Options are, well, optional, but it is recommended to provide the following ones (otherwise, it uses default generic options):

• --namespace <value> – internal namespace for the block name
• --title <value> – display title for the block
• --short-description <value> – short description for the block
• --category <name> – under what category the block is displayed

Running the command creates a new directory with the slug as its name (in this case, todo-list):

Scaffolding a new block through @wordpress/create-block. (Image from developer.wordpress.org)

The directory will contain all the files required by the plugin and the block:

todo-list/
├──build/
│ ├── index.asset.php
│ ├── style.css
│ ├── style-index.css
│ └── index.js
├── src/
│ └── index.js
├── .gitignore
├── .editorconfig
├── block.json
├── package.json
├── package-lock.json
├── todo-list.php
└── readme.txt

• block.json contains the metadata required by the block directory
• readme.txt contains the information required by the plugin directory
• todo-list.php (following the provided slug) is the plugin’s main file
• package.json defines all the JavaScript dependencies by the block
• src/index.js is the entry to the block
• build/index.js is the compiled JavaScript code
• build/style.css and build/style-index.css are the compiled CSS files, containing the styles extracted from Sass files

With the project created, we can step on the directory in the terminal, and execute the following commands:

• npm start – starts the build for development
• npm run build – builds the code for production
• npm run format:js – formats JavaScript files
• npm run lint:css – lints CSS files
• npm run lint:js – lints JavaScript files
• npm run packages-update – updates WordPress packages to the latest version

#gutenberg #wordpress #react #javascript #web-development