@wordpress/create-block - Gutenberg Block Editor

@wordpress/create-block is the official tool for scaffolding WordPress plugins that register blocks. It generates PHP, JS, and CSS code with a modern build setup requiring zero configuration.

Quick Start

Generate a new block plugin

npx @wordpress/create-block@latest todo-list

This creates a new plugin folder named todo-list.

Navigate to the plugin directory

cd todo-list

Start development

npm start

The build will automatically rebuild when you make changes.

Install the plugin

Copy the generated folder to your WordPress wp-content/plugins/ directory and activate it from the WordPress admin.

Requires Node.js >= 20.10.0 and npm >= 10.2.3

Usage

Basic Command

npx @wordpress/create-block@latest [options] [slug]

The slug defines:

Block slug (for identification)
Output folder name
WordPress plugin name

Interactive Mode

When you run the command without a slug, it prompts you for input:

Terminal

$ npx @wordpress/create-block@latest

? What is the slug for your block? my-awesome-block
? What is the internal namespace for your block? my-namespace
? What is the display title for your block? My Awesome Block
? What is the short description for your block? A custom block for awesome things
? What is the dashicon to make it easier to identify your block? star-filled
? What category should the block be assigned? widgets

Options

—template

Specify an external npm package or local directory as a template.

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

—variant

Generate a dynamic block variant:

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

This creates a dynamic block that renders on the server.

—namespace

Specify a custom namespace for your block:

npx @wordpress/create-block@latest my-block --namespace=my-namespace

This creates my-namespace/my-block instead of create-block/my-block. Update the namespace in:

block.json - the name property

—no-plugin

Scaffold only block files without the plugin wrapper:

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

This runs in “No plugin mode” and scaffolds block files into the current directory.

—target-dir

Specify the output directory:

npx @wordpress/create-block@latest my-block --target-dir=custom-folder

—title

Set the display title for the block and plugin:

npx @wordpress/create-block@latest my-block --title="My Custom Block"

—short-description

Set the short description:

npx @wordpress/create-block@latest my-block --short-description="A block for custom content"

—category

Set the block category:

npx @wordpress/create-block@latest my-block --category=widgets

Available categories:

text
media
design
widgets
theme
embed

—wp-scripts

Enable or disable integration with @wordpress/scripts:

# Enable (default)
npx @wordpress/create-block@latest my-block --wp-scripts

# Disable
npx @wordpress/create-block@latest my-block --no-wp-scripts

—wp-env

Add @wordpress/env configuration to the generated plugin:

npx @wordpress/create-block@latest my-block --wp-env

This allows you to easily set up a local WordPress environment for testing:

Generate block with wp-env

npx @wordpress/create-block@latest my-block --wp-env
cd my-block

Start local environment

npm run wp-env start

Access WordPress

Open http://localhost:8888

Username: admin
Password: password

—textdomain

Set a custom text domain for internationalization:

npx @wordpress/create-block@latest my-block --textdomain=my-custom-domain

If not specified, the block’s slug is used as the default text domain.

—version

Display version information:

npx @wordpress/create-block@latest --version

—help

Display usage information:

npx @wordpress/create-block@latest --help

Complete Options Reference

Options:
  -V, --version                output the version number
  -t, --template <name>        project template type name
  --variant                    choose a block variant
  --no-plugin                  scaffold block files only
  --target-dir <directory>     output directory (defaults to slug)
  --namespace <value>          internal namespace for the block
  --title <value>              display title for the block
  --short-description <value>  short description
  --category <name>            category name for the block
  --wp-scripts                 enable @wordpress/scripts integration
  --no-wp-scripts              disable @wordpress/scripts integration
  --wp-env                     enable @wordpress/env integration
  --textdomain <value>         text domain for i18n
  -h, --help                   output usage information

Generated Project Structure

When you run create-block, it generates this structure:

my-block/
├── build/              # Compiled assets (generated)
├── src/
│   ├── block.json      # Block metadata
│   ├── edit.js         # Editor component
│   ├── editor.scss     # Editor styles
│   ├── index.js        # Block registration
│   ├── save.js         # Save component
│   └── style.scss      # Front-end and editor styles
├── .editorconfig       # Editor configuration
├── .gitignore          # Git ignore rules
├── my-block.php        # Main plugin file
├── package.json        # npm dependencies and scripts
└── readme.txt          # WordPress plugin readme

Available Scripts in Generated Project

The generated plugin includes these npm scripts:

npm start

Starts the build for development with watch mode.

npm start

Automatically rebuilds when you make changes to the code.

npm run build

Builds the code for production.

npm run build

Generates optimized assets in the build folder.

npm run format

Formats files using Prettier.

npm run format

npm run lint:css

Lints CSS files using Stylelint.

npm run lint:css

npm run lint:js

Lints JavaScript files using ESLint.

npm run lint:js

npm run packages-update

Updates WordPress packages to the latest versions.

npm run packages-update

npm run plugin-zip

Creates a ZIP file of the plugin.

npm run plugin-zip

Useful for distributing your plugin.

You don’t need to configure webpack, Babel, or ESLint yourself. They’re preconfigured and hidden so you can focus on coding.

Examples

Create a Block with Custom Namespace

npx @wordpress/create-block@latest testimonial --namespace=acme

This creates:

Block name: acme/testimonial
Plugin folder: testimonial

Create a Dynamic Block

npx @wordpress/create-block@latest latest-posts --variant=dynamic

Generates a dynamic block that renders on the server, useful for displaying database-driven content.

Create Multiple Blocks (No Plugin Mode)

Add a new block to an existing plugin:

cd my-existing-plugin/src/blocks
npx @wordpress/create-block@latest new-block --no-plugin

Create Block with Local Development Environment

npx @wordpress/create-block@latest my-block --wp-env
cd my-block
npm run wp-env start

Access your block at http://localhost:8888

Create Block from Custom Template

npx @wordpress/create-block@latest my-block --template=@company/block-template

Block Development Workflow

Generate the block

npx @wordpress/create-block@latest feature-card
cd feature-card

Start development server

npm start

Watches for file changes and rebuilds automatically.

Edit block code

Modify files in the src directory:

block.json - block metadata
edit.js - editor interface
save.js - front-end output
style.scss - front-end and editor styles
editor.scss - editor-only styles

Test in WordPress

Copy the plugin folder to wp-content/plugins/
Activate the plugin in WordPress admin
Add the block to a post or page

Build for production

npm run build

Creates optimized production assets.

Create distribution package

npm run plugin-zip

Generates a ZIP file ready for distribution.

Understanding block.json

The block.json file contains your block’s metadata:

src/block.json

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "create-block/my-block",
  "version": "0.1.0",
  "title": "My Block",
  "category": "widgets",
  "icon": "smiley",
  "description": "Example block scaffolded with Create Block tool.",
  "supports": {
    "html": false
  },
  "textdomain": "my-block",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

Key fields:

name - unique block identifier (namespace/slug)
title - display name in the editor
category - where the block appears in the inserter
icon - Dashicon or custom SVG
editorScript - JavaScript for the editor
editorStyle - CSS for the editor only
style - CSS for both editor and front-end

Block Templates

Create Block supports custom templates for different use cases.

Built-in Templates

npx @wordpress/create-block@latest my-block --template=static

External Templates

You can use external npm packages as templates:

npx @wordpress/create-block@latest my-block --template=@my-org/custom-template

Or local templates:

npx @wordpress/create-block@latest my-block --template=./templates/custom

Tips and Best Practices

Use semantic block names

Choose descriptive, semantic names:Good:

testimonial
pricing-table
feature-grid

Avoid:

block1
custom-block
my-block

Keep namespace consistent

Use your company or project name as the namespace:

npx @wordpress/create-block@latest testimonial --namespace=acme

All your blocks should use the same namespace (e.g., acme/testimonial, acme/pricing-table).

Pair blocks with plugins, not themes

Blocks should be part of plugins, not themes. This ensures blocks continue working when users change themes.

Use wp-env for local testing

Add --wp-env flag to quickly test your block:

npx @wordpress/create-block@latest my-block --wp-env
cd my-block
npm run wp-env start

Keep dependencies updated

Regularly update WordPress packages:

npm run packages-update
npm install
npm run build

Troubleshooting

Node version error

Error: create-block requires Node.js 20.10.0 or higherSolution: Update Node.js:

# Using nvm
nvm install 20
nvm use 20

# Verify version
node --version

Block not appearing in editor

Checklist:

Is the plugin activated?
Did you run npm run build or npm start?
Are there errors in the browser console?
Is the block name in block.json unique?

Build errors

Solution: Clean install dependencies:

rm -rf node_modules package-lock.json
npm install
npm run build

Styles not loading

Check:

Are style imports in index.js?
Did the build complete successfully?
Are the CSS files in the build folder?
Is the plugin enqueuing assets correctly?

Next Steps

After creating your block:

Block Editor Handbook

Learn about block development concepts and APIs

Block API Reference

Explore block registration and block.json options

@wordpress/scripts

Learn about available build commands and options

@wordpress/env

Set up a local WordPress environment for testing

Package Information

Version: 4.83.0
Node.js: >= 20.10.0
npm: >= 10.2.3
License: GPL-2.0-or-later
Binary: wp-create-block

@wordpress/scripts - Build and test scripts
@wordpress/env - Local WordPress environment
@wordpress/block-editor - Block editor components

Core Packages

UI Components

Editor Implementations

Developer Tools

Utilities

​Quick Start

​Usage

​Basic Command

​Interactive Mode

​Options

​—template

​—variant

​—namespace

​—no-plugin

​—target-dir

​—title

​—short-description

​—category

​—wp-scripts

​—wp-env

​—textdomain

​—version

​—help

​Complete Options Reference

​Generated Project Structure

​Available Scripts in Generated Project

​Examples

​Create a Block with Custom Namespace

​Create a Dynamic Block

​Create Multiple Blocks (No Plugin Mode)

​Create Block with Local Development Environment

​Create Block from Custom Template

​Block Development Workflow

​Understanding block.json

​Block Templates

​Built-in Templates

​External Templates

​Tips and Best Practices

​Troubleshooting

​Next Steps

Block Editor Handbook

Block API Reference

@wordpress/scripts

@wordpress/env

​Package Information

​Related Packages

Build docs developers (and LLMs) love

Quick Start

Usage

Basic Command

Interactive Mode

Options

—template

—variant

—namespace

—no-plugin

—target-dir

—title

—short-description

—category

—wp-scripts

—wp-env

—textdomain

—version

—help

Complete Options Reference

Generated Project Structure

Available Scripts in Generated Project

Examples

Create a Block with Custom Namespace

Create a Dynamic Block

Create Multiple Blocks (No Plugin Mode)

Create Block with Local Development Environment

Create Block from Custom Template

Block Development Workflow

Understanding block.json

Block Templates

Built-in Templates

External Templates

Tips and Best Practices

Troubleshooting

Next Steps

Package Information

Related Packages