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.

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

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

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

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

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

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

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

Are you looking for a way to share your project configuration? Creating an external project template hosted on npm or located in a local directory is possible. These npm packages can provide custom .mustache files that replace default files included in the tool for the WordPress plugin or/and the block. It's also possible to override default configuration values used during the scaffolding process.

Project Template Configuration

Providing the main file (index.js by default) for the package that returns a configuration object is mandatory. Several options allow customizing the scaffolding process.

`pluginTemplatesPath`

This optional field allows overriding file templates related to the WordPress plugin shell. The path points to a location with template files ending with the .mustache extension (nested folders are also supported). When not set, the tool uses its own set of templates.

Example:

const { join } = require( 'path' );

module.exports = {
	pluginTemplatesPath: join( __dirname, 'plugin-templates' ),
};

`blockTemplatesPath`

This optional field allows overriding file templates related to the individual block. The path points to a location with template files ending with the .mustache extension (nested folders are also supported). When not set, the tool uses its own set of templates.

Example:

const { join } = require( 'path' );

module.exports = {
	blockTemplatesPath: join( __dirname, 'block-templates' ),
};

`assetsPath`

This setting is useful when your template scaffolds a WordPress 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',
	},
};

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.

Project:

wpScripts (default: true) – enables integration with the @wordpress/scripts package and adds common scripts to the package.json.
wpEnv (default: false) – enables integration with the @wordpress/env package and adds the env script to the package.json.
customScripts (default: {}) – the list of custom scripts to add to package.json . It also allows overriding default scripts.
npmDependencies (default: []) – the list of remote npm packages to be installed in the project with npm install when wpScripts is enabled.
npmDevDependencies (default: []) – the list of remote npm packages to be installed in the project with npm install --save-dev when wpScripts is enabled.

Plugin header fields (learn more):

pluginURI (no default) – the home page of the plugin.
version (default: '0.1.0') – the current version number of the plugin.
author (default: 'The WordPress Contributors') – the name of the plugin author(s).
license (default: 'GPL-2.0-or-later') – the short name of the plugin’s license.
licenseURI (default: 'https://www.gnu.org/licenses/gpl-2.0.html') – a link to the full text of the license.
domainPath (no default) – a custom domain path for the translations (more info).
updateURI: (no default) – a custom update URI for the plugin (related dev note).

Block metadata (learn more):

folderName (default: .) – the location for the block.json file and other optional block files generated from block templates included in the folder set with the blockTemplatesPath setting.
$schema (default: https://schemas.wp.org/trunk/block.json) – the schema URL used for block validation.
apiVersion (default: 2) – the block API version (related dev note).
slug (no default) – the block slug used for identification in the block name.
namespace (default: 'create-block') – the internal namespace for the block name.
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 (available values).
category (default: 'widgets') – blocks are grouped into categories to help users browse and discover them. The categories provided by core are text, media, design, widgets, theme, and embed.
attributes (no default) – block attributes (more details).
supports (no default) – optional block extended support features (more details.
editorScript (default: 'file:./index.js') – an editor script definition.
editorStyle (default: 'file:./index.css') – an editor style definition.
style (default: 'file:./style-index.css') – a frontend and editor style definition.

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Create Block

Description

Quick start

Usage

Available Commands

External Project Templates

Project Template Configuration

`pluginTemplatesPath`

`blockTemplatesPath`

`assetsPath`

`defaultValues`

Contributing to this package

Files

README.md

Latest commit

History

README.md

File metadata and controls

Create Block

Description

Quick start

Usage

Available Commands

External Project Templates

Project Template Configuration

pluginTemplatesPath

blockTemplatesPath

assetsPath

defaultValues

Contributing to this package

`pluginTemplatesPath`

`blockTemplatesPath`

`assetsPath`

`defaultValues`