README.md

Create Block

Create Block is an officially supported tool for scaffolding WordPress plugins with blocks. It generates PHP, JS, CSS code, and everything you need to start the project. It 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.

Description

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

Visit the Gutenberg handbook to learn more about Block API.

Quick start

You only need to provide the slug – the target location for scaffolded plugin files and the internal block name.

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

(requires node version 14.0.0 or above, and npm version 6.14.4 or above)

It creates a WordPress plugin that you need to install manually.

Watch a video introduction to create-block on Learn.wordpress.org

Usage

The following command generates a project with PHP, JS, and CSS code for registering a block with a WordPress plugin.

$ 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 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
--no-plugin                  scaffold block files only
--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
--variant                    choose a block variant as defined by the template

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

2. External npm package – it is also possible to select an external npm package as a template.

$ npx @wordpress/create-block --template my-template-package

3. Local template directory – it is also possible to pick a local directory as a template.

$ npx @wordpress/create-block --template ./path/to/template-directory

4. Generating a dynamic block based on the built-in template.

$ npx @wordpress/create-block --variant dynamic

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

$ npx @wordpress/create-block --help

5. No plugin mode – it is also possible to scaffold only block files into the current directory.

$ npx @wordpress/create-block --no-plugin

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. 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.

Available Commands

When bootstrapped with the static template (or any other project template with wpScripts flag enabled), you can run several commands inside the directory:

$ npm start

Starts the build for development. Learn more.

$ npm run build

Builds the code for production. Learn more.

$ npm run format

Formats files. Learn more.

$ npm run lint:css

Lints CSS files. Learn more.

$ npm run lint:js

Lints JavaScript files. Learn more.

$ npm run plugin-zip

Creates a zip file for a WordPress plugin. Learn more.

$ npm run packages-update

Updates WordPress packages to the latest version. Learn more.

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.

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.