@wordpress/create-block Edit

Create Block is 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.

Description Description

Blocks are the fundamental element of the WordPress block editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor.

Visit the Gutenberg handbook to learn more about Block API.

Top ↑

Quick start Quick start


You just need to provide the slug which is the target location for scaffolded files and the internal block name.

$ npx @wordpress/create-block todo-list
$ cd todo-list
$ npm start

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

You don’t need to install or configure tools like webpack, Babel or ESLint yourself. They are preconfigured and hidden so that you can focus on the code.

Top ↑

Usage Usage

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

$ npx @wordpress/create-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 unless overriden with some of the options listed below.


-V, --version                output the version number
-t, --template <name>        block template type name, allowed values: "es5", "esnext" (default: "esnext")
--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>            category name for the block
--wp-scripts                 enable integration with `@wordpress/scripts` package
--no-wp-scripts              disable integration with `@wordpress/scripts` package
-h, --help                   output usage information

Please note that --version and --help options don’t work with npm init. You have to use npx instead, as presented in the examples.

More examples:

  1. Interactive mode – without giving a project name, the script will run in interactive mode giving a chance to customize the important options before generating the files.
$ npx @wordpress/create-block
  1. 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.
$ npx @wordpress/create-block --template es5
  1. 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.

Top ↑

Available Commands 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 format:js

Formats JavaScript files. 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.

Top ↑


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.

Code is Poetry.