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

1
Ensure Node.js is Installed
2
Start by ensuring you have Node.js and npm installed on your computer. Review the Node.js development environment guide if not.
3
Requirements: Node.js version 20.10.0 or above, and npm version 10.2.3 or above.
4
Scaffold a Block
5
Run the following command to scaffold an example block plugin:
6
npm
npx @wordpress/create-block@latest todo-list
cd todo-list
yarn
yarn create @wordpress/block@latest todo-list
cd todo-list
pnpm
pnpm create @wordpress/block@latest todo-list
cd todo-list
7
The slug provided (todo-list) defines:
8
  • The folder name for the scaffolded plugin
  • The internal block name
  • The name of the WordPress plugin
    • 9
    Install the Plugin
    10
    The WordPress plugin generated must be installed manually.
    11
    You can use wp-env from inside the generated plugin folder to create a local WordPress development environment with your new block plugin installed and activated.
    12
    If you have your own local WordPress development environment already set up, copy the plugin folder to the wp-content/plugins/ directory.
    13
    Activate the Plugin
    14
    Navigate to the Plugins page of your local WordPress installation and activate the “Todo List” plugin. The example block will then be available in the Editor.
    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: 
    {
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  }
}

    ​
    Development Workflow

    The two scripts you will use most often are start and build: 
    # Development with auto-rebuild
npm start

# Production build
npm run 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: 
    npx @wordpress/create-block@latest [options] [slug]

    ​
    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: 
    npx @wordpress/create-block@latest

    ​
    Advanced Usage

    ​
    Custom Namespace

    By default, blocks are created with the create-block namespace. You should specify your own unique namespace: 
    npx @wordpress/create-block@latest my-block --namespace=my-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: 
    npx @wordpress/create-block@latest --variant dynamic

    ​
    No Plugin Mode

    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

    ​
    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: 
    npx @wordpress/create-block@latest --wp-env

    ​
    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: 
    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
    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: 
    npx @wordpress/create-block@latest \
  --namespace="my-plugin" \
  --slug="my-block" \
  --variant="dynamic" \
  --title="My Custom Block" \
  --short-description="A custom block for my site"

    ​
    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

    Build docs developers (and LLMs) love

    Get started for freeTalk to us