Create Block
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
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.
Quick start
You just need to provide the slug
which is 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 12.0.0
or above, and npm
version 6.9.0
or above)
It creates a WordPress plugin that you need to install manually.
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 overridden with some of the options listed below.
Options:
-V, --version output the version number
-t, --template <name> plugin template type name, allowed values: "es5", "esnext", the name of an external npm package (default: "esnext"), or the path to a local directory.
--namespace <value> internal namespace for the block name
--title <value> display title for the plugin/block
--short-description <value> short description for the plugin/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
--wp-env enable integration with `@wordpress/env` package
-h, --help output usage information
More examples:
- 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
- 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
- Local template directory – it is also possible to pick a local directory as a template.
$ npx @wordpress/create-block --template ./path/to/template
- 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
When bootstrapped with the esnext
template (or any external 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 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 Templates
Since version 0.19.0
it is possible to use external templates hosted on npm. These packages need to contain .mustache
files that will be used during the block scaffolding process.
Template Configuration
It is mandatory to provide the main file (index.js
by default) for the package that returns a configuration object. It must contain at least the templatesPath
field.
templatesPath
A mandatory field with the path pointing to the location where plugin template files live (nested folders are also supported). All files without the .mustache
extension will be ignored.
Example:
const { join } = require( 'path' );
module.exports = {
templatesPath: join( __dirname, 'plugin-templates' ),
};
blockTemplatesPath
An optional field with the path pointing to the location where template files for the individual block live (nested folders are also supported). All files without the .mustache
extension will be ignored.
Example:
const { join } = require( 'path' );
module.exports = {
blockTemplatesPath: join( __dirname, 'block-templates' ),
};
assetsPath
This setting is useful when your template scaffolds a plugin that uses static assets like images or fonts, which should not be processed. It provides the path pointing to the location where assets are located. They will be copied to the assets
subfolder in the generated plugin.
Example:
const { join } = require( 'path' );
module.exports = {
assetsPath: join( __dirname, 'plugin-assets' ),
};
defaultValues
It is possible to override the default template configuration using the defaultValues
field.
Example:
module.exports = {
defaultValues: {
slug: 'my-fantastic-block',
title: 'My fantastic block',
dashicon: 'palmtree',
version: '1.2.3',
},
templatesPath: __dirname,
};
The following configurable variables are used with the template files. Template authors can change default values to use when users don't provide their data:
-
$schema
(default:https://schemas.wp.org/trunk/block.json
) -
apiVersion
(default:2
) - see https://make.wordpress.org/core/2020/11/18/block-api-version-2/. -
slug
(no default) -
namespace
(default:'create-block'
) -
title
(no default) - a display title for your block. -
description
(no default) - a short description for your block. -
dashicon
(no default) - an icon property thats makes it easier to identify a block, see https://developer.wordpress.org/resource/dashicons/. -
category
(default:'widgets'
) - blocks are grouped into categories to help users browse and discover them. The categories provided by core aretext
,media
,design
,widgets
,theme
, andembed
. -
attributes
(no default) - see https://developer.wordpress.org/block-editor/developers/block-api/block-attributes/. -
supports
(no default) - optional block extended support features, see https://developer.wordpress.org/block-editor/developers/block-api/block-supports/. -
author
(default:'The WordPress Contributors'
) -
license
(default:'GPL-2.0-or-later'
) -
licenseURI
(default:'https://www.gnu.org/licenses/gpl-2.0.html'
) -
version
(default:'0.1.0'
) -
wpScripts
(default:true
) -
wpEnv
(default:false
) - enables integration with the@wordpress/env
package and adds theenv
command to the package.json. -
npmDependencies
(default:[]
) – the list of remote npm packages to be installed in the project withnpm install
whenwpScripts
is enabled.customScripts
(default: {}) - the list of custom scripts to add topackage.json
. It also allows overriding default scripts. -
folderName
(default:.
) – the location for theblock.json
file and other optional block files generated from block templates included in the folder set with theblockTemplatesPath
setting. -
editorScript
(default:'file:./build/index.js'
) -
editorStyle
(default:'file:./build/index.css'
) -
style
(default:'file:./build/style-index.css'
)
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.