Create Block is an officially supported tool for scaffolding a WordPress plugin that registers a block. It generates PHP, JS, CSS code, and everything you need to start the project. It also integrates a modern build setup with no configuration.
It is largely inspired by create-react-app. Major kudos to @gaearon, the whole Facebook team, and the React community.
Blocks are the fundamental elements of modern WordPress sites. Introduced in WordPress 5.0, they allow page and post builder-like functionality to every up-to-date WordPress website.
Learn more about the Block API at the Gutenberg HandBook.
Quick start
$ npx @wordpress/create-block@latest todo-list
$ cd todo-list
$ npm start
The slug
provided (todo-list
in the example) defines the folder name for the scaffolded plugin and the internal block name. The WordPress plugin generated must be installed manually.
(requires node
version 20.10.0
or above, and npm
version 10.2.3
or above)
Watch a video introduction to create-block on Learn.wordpress.org
Usage
The create-block
command generates a project with PHP, JS, and CSS code for registering a block with a WordPress plugin.
$ npx @wordpress/create-block@latest [options] [slug]
The name for a block is a unique string that identifies a block. Block Names are structured as
namespace
/slug
, where namespace is the name of your plugin or theme.In most cases, we recommended pairing blocks with WordPress plugins rather than themes, because only using plugin ensures that all blocks still work when your theme changes.
Interactive Mode
When no slug
is provided, the script will run in interactive mode and will start prompting for the input required (slug
, title, namespace…) to scaffold the project.
slug
The use of slug
is optional.
When provided it triggers the quick mode, where this slug
is used:
- as the block slug (required for its identification)
- as the output location (folder name) for scaffolded files
- as the name of the WordPress plugin.
The rest of the configuration is set to all default values unless overridden with some options listed below.
options
-V, --version output the version number
-t, --template <name> project template type name; allowed values: "static" (default), "es5", the name of an external npm package, or the path to a local directory
--variant choose a block variant as defined by the template
--no-plugin scaffold block files only
--target-dir <directory> the directory where the files will be scaffolded, defaults to the slug
--namespace <value> internal namespace for the block name
--title <value> display title for the block and the WordPress plugin
--short-description <value> short description for the block and the WordPress plugin
--category <name> category name for the block
--wp-scripts enable integration with `@wordpress/scripts` package
--no-wp-scripts disable integration with `@wordpress/scripts` package
--wp-env enable integration with `@wordpress/env` package
-h, --help output usage information
--template
This argument specifies an external npm package as a template.
$ npx @wordpress/create-block@latest --template my-template-package
This argument also allows to pick a local directory as a template.
$ npx @wordpress/create-block@latest --template ./path/to/template-directory
--variant
With this argument, create-block
will generate a dynamic block based on the built-in template.
$ npx @wordpress/create-block@latest --variant dynamic
--no-plugin
With this argument, the create-block
package runs in No plugin mode which only scaffolds block files into the current directory.
$ npx @wordpress/create-block@latest --no-plugin
--wp-env
With this argument, the create-block
package will add to the generated plugin the configuration and the script to run wp-env
package within the plugin. This will allow you to easily set up a local WordPress environment (via Docker) for building and testing the generated plugin.
$ npx @wordpress/create-block@latest --wp-env
--help
With this argument, the create-block
package outputs usage information.
$ npx @wordpress/create-block@latest --help
Available commands in the scaffolded project
The plugin folder created when executing this command, is a node package with a modern build setup that requires no configuration.
A set of scripts is available from inside that folder (provided by the scripts
package) to make your work easier. Click here for a full description of these commands.
Note: 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 coding.
For example, running the start
script from inside the generated folder (npm start
) would automatically start the build for development.
External Project Templates
Click here for information on External Project Templates
Contributing to this package
This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.