wp scaffold block

Overview

Generate all the boilerplate files needed to create a custom Gutenberg (Block Editor) block — including block.json, edit.js, save.js, editor.css, and style.css. Skip the manual setup and start writing real block logic immediately.

What It Does

wp scaffold block creates a structured directory inside a plugin with all the files required by the WordPress Block API. The scaffold follows the official WordPress block development standards and works with @wordpress/scripts or manual webpack builds.

Syntax

wp scaffold block <slug> [OPTIONS]

Options

Flag	Description
SLUG	Block slug (used for directory name and block name)
--title=TITLE	Human-readable block title (default: derived from slug)
--dashicon=DASHICON	Dashicon name for the block icon (e.g., format-image)
--category=CATEGORY	Block category: common, formatting, layout, widgets, embed
--plugin=PLUGIN	Plugin slug to scaffold block inside
--theme	Scaffold inside the active theme instead of a plugin
--namespace=NAMESPACE	Block namespace (default: myplugin)
--force	Overwrite existing files

Basic Usage

Scaffold a block inside a plugin

wp scaffold block my-button \
  --title="My Button Block" \
  --category=common \
  --plugin=my-plugin

Output:

Success: Created block 'My Button Block'.

Generated file structure:

wp-content/plugins/my-plugin/
└── blocks/
    └── my-button/
        ├── block.json
        ├── edit.js
        ├── save.js
        ├── editor.css
        └── style.css

Real-World Scenarios

Scenario 1: Create a testimonial block

wp scaffold block testimonial \
  --title="Testimonial Block" \
  --dashicon=format-quote \
  --category=common \
  --plugin=my-blocks-plugin \
  --namespace=mysite

Scenario 2: Create a block inside the active theme

wp scaffold block hero-banner \
  --title="Hero Banner" \
  --category=layout \
  --theme

Generated block.json (Example)

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "mysite/testimonial",
  "version": "0.1.0",
  "title": "Testimonial Block",
  "category": "common",
  "icon": "format-quote",
  "description": "A custom Testimonial Block block.",
  "supports": {
    "html": false
  },
  "textdomain": "my-blocks-plugin",
  "editorScript": "file:./edit.js",
  "editorStyle": "file:./editor.css",
  "style": "file:./style.css"
}

Best Practices

1. Use --namespace to avoid naming collisions with other plugins.
2. Always use --plugin to scope the block to a specific plugin.
3. After generating, register the block in your plugin's main PHP file: register_block_type( __DIR__ . '/blocks/my-button' );

Quick Reference

wp scaffold block <slug> --plugin=<plugin>
wp scaffold block <slug> --theme

Next Steps

• wp scaffold plugin — scaffold the plugin first.
• wp scaffold child-theme — scaffold a theme to host blocks.