Skip to main content
Custom blocks for the Block Editor in WordPress are typically registered using plugins and are defined through a specific set of files. The @wordpress/create-block package is an officially supported tool to scaffold the structure of files needed to create and register a block. It generates all the necessary code to start a project and integrates a modern JavaScript build setup (using wp-scripts) with no configuration required. The package is designed to help developers quickly set up a block development environment following WordPress best practices.
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.

​
Quick Start

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

​
Basic Usage

The create-block package assumes you will use modern JavaScript (ESNext and JSX) to build your block. This requires a build step to compile the code into a format that browsers can understand. Luckily, the wp-scripts package handles this process for you. When create-block scaffolds the block, it installs wp-scripts and adds the most common scripts to the block’s package.json file:

​
Development Workflow

The two scripts you will use most often are start and build:
  • npm start - Starts a development server and automatically rebuilds the block whenever any code change is detected
  • npm run build - Optimizes your code and makes it production-ready
Refer to the Get started with wp-scripts for an introduction to this package.

​
Command Options

The create-block command provides several options for customization:

​
Available 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
  • --textdomain <value> - Text domain for internationalization
  • -h, --help - Output usage information

​
Interactive Mode

For developers who prefer a more guided experience, the create-block package provides an interactive mode. Instead of manually specifying all options upfront, this mode will prompt you for inputs step-by-step. To use this mode, run the command:

​
Advanced Usage

​
Custom Namespace

By default, blocks are created with the create-block namespace. You should specify your own unique namespace:
This creates my-namespace/my-block instead of create-block/my-block. If you’ve already created a block, update the namespace in block.json - the name property.

​
Dynamic Block Variant

With this argument, create-block will generate a dynamic block based on the built-in template:

​
No Plugin Mode

With this argument, the create-block package runs in No plugin mode which only scaffolds block files into the current directory:

​
With wp-env Integration

With this argument, the create-block package will add to the generated plugin the configuration and the script to run wp-env within the plugin. This will allow you to easily set up a local WordPress environment (via Docker) for building and testing the generated plugin:

​
Using External Templates

The create-block package also supports the use of templates, enabling you to create blocks based on predefined configurations and structures. This argument specifies an external npm package as a template:
This argument also allows to pick a local directory as a template:
Templates must be set up in advance so the create-block package knows where to find them. Learn more in the External Project Templates guide.

​
Quick Start with Options

If you’re already familiar with the create-block options and want a more streamlined setup, you can use quick start mode. This allows you to pass specific options directly in the command line:

​
Block Name Structure

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 recommend pairing blocks with WordPress plugins rather than themes, because only using plugin ensures that all blocks still work when your theme changes.

​
Available Commands in 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:
  • npm start - Starts the build for development
  • npm run build - Builds the code for production
  • npm run format - Formats files
  • npm run lint:css - Lints CSS files
  • npm run lint:js - Lints JavaScript files
  • npm run packages-update - Updates WordPress packages to the latest version
  • npm run plugin-zip - Creates a zip file for a WordPress plugin
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.

​
Additional Resources