| name | wp-block-development |
| description | WordPress block editor code review and Gutenberg block development patterns for WordPress 6.x+. Use when reviewing block code, auditing block.json schema, checking editor components, validating render callbacks, analyzing block attributes, verifying InnerBlocks usage, detecting block validation errors, reviewing Interactivity API directives, or when user mentions "block review", "Gutenberg", "block development", "block editor", "block.json", "useBlockProps", "InnerBlocks", "Interactivity API", "data-wp-bind", "render_callback", "dynamic block", "static block", "block deprecation", "block attributes", "block supports", "@wordpress/scripts", "wp-scripts", "block validation error", "save function", "RichText", "InspectorControls", "BlockControls". Detects issues in block.json schema, React/JSX editor patterns, server-side rendering, attribute handling, and frontend interactions. |
WordPress Block Development Review Skill
Overview
Systematic block development review for WordPress 6.x+ block editor (Gutenberg). Core principle: WordPress blocks follow a dual-architecture pattern—React components for the editor (edit function) and either static HTML (save function) or server-side PHP (render_callback/render file) for the frontend. block.json is the single source of truth. Review validates block.json schema, editor patterns (React/JSX), server-side rendering (PHP), attribute handling, deprecation management, and Interactivity API usage. Report findings grouped by file (PHP and JS/JSX files intermixed by actual path) with line numbers, severity labels (CRITICAL/WARNING/INFO), and BAD/GOOD code pairs.
Note: This skill reviews BOTH PHP and JavaScript/React code. PHP follows WordPress PHP Coding Standards (spaces in parentheses, array() not [], Yoda conditions). JavaScript/JSX follows WordPress JS coding standards (tab indentation, JSDoc comments, camelCase for variables/functions, PascalCase for components).
When to Use
Use when:
- Block plugin code review (single block, multi-block, or block library)
- block.json schema validation and field verification
- Editor component review (edit/save functions, React/JSX patterns)
- Render callback or render file audit (server-side PHP)
- InnerBlocks pattern review (nested blocks, template, templateLock)
- Block deprecation check (save function migrations)
- Interactivity API directive review (WP 6.5+ frontend interactions)
- Block attribute schema validation (type, source, selector, default)
- @wordpress/scripts build configuration check
- Block validation error investigation
- useBlockProps, RichText, InspectorControls, BlockControls usage
Don't use for:
- theme.json configuration (use wp-theme-development when available)
- General React application review (this is block-editor-specific)
- WooCommerce block extensions (use wp-woocommerce-dev when available)
- Security-only audits (use wp-security-review for comprehensive security analysis)
- Plugin architecture audits (use wp-plugin-development for plugin structure)
- Performance-only audits (use wp-performance-review)
Code Review Workflow
Follow this seven-step workflow for systematic block reviews:
-
Identify block type and context
- Single block plugin → One block.json, simple structure
- Multi-block plugin → Multiple blocks in src/block-one/, src/block-two/
- Block library/collection → Published as package, namespacing critical
- Theme blocks → Registered in functions.php, different loading context
-
Validate block.json schema (BLK-02, BLK-06, BLK-08, BLK-10)
- apiVersion must be 3 (WP 6.3+). Flag 1 or 2 as WARNING with upgrade guidance.
- name must be "namespace/block-name" format (lowercase, letters, numbers, dashes)
- title, category required
- attributes: validate type, source, selector, default values. Flag type mismatches.
- supports: color, spacing, typography, align, anchor, html
- editorScript, script, viewScript, viewScriptModule: validate "file:./path" format
- style, editorStyle: validate paths
- render: "file:./render.php" for dynamic blocks
- $schema field recommended for validation
-
Check edit function (BLK-05, BLK-20)
- useBlockProps() MUST be called and spread on wrapper element
- Import pattern: @wordpress/* packages (GOOD) vs window.wp.* (BAD - legacy)
- InspectorControls for sidebar settings, BlockControls for toolbar
- RichText proper usage (tagName, value, onChange, allowedFormats)
- InnerBlocks with allowedBlocks and template props
- useSelect/useDispatch from @wordpress/data (combine selectors in single useSelect call)
- i18n: all user-facing strings wrapped in __() from @wordpress/i18n with text domain
-
Check save function or render callback
- Static blocks: useBlockProps.save() MUST be called, RichText.Content for rich text, InnerBlocks.Content for nested blocks
- Dynamic blocks: save returns null (or InnerBlocks.Content if nested blocks used - BLK-14 CRITICAL)
- Save function must be DETERMINISTIC - no random values, no Date.now(), no side effects
- Render callback/render.php: get_block_wrapper_attributes() for wrapper, escape all output (esc_html, esc_attr, esc_url, wp_kses_post but NOT on $content from InnerBlocks - BLK-21), defined( 'ABSPATH' ) || exit; at top
-
Scan for CRITICAL patterns
- Missing apiVersion or using 1/2 instead of 3
- window.wp.* instead of @wordpress/* imports in JS/JSX
- save function without useBlockProps.save() (apiVersion 3)
- render callback using wp_kses_post() on $content parameter (breaks embeds)
- Dynamic block with InnerBlocks but save returns null (no InnerBlocks.Content)
- Attribute with source: 'meta' (deprecated - use useEntityProp)
- Invalid attribute type/source combination
- Missing register_block_type() call in PHP
-
Check WARNING patterns
- block.json missing supports field
- edit function without useBlockProps()
- Hardcoded strings not wrapped in __() in JS/JSX or PHP
- render.php without get_block_wrapper_attributes()
- PHP render files without defined( 'ABSPATH' ) check
- save function with side effects (Math.random, Date.now)
- Missing block.json $schema field
- useSelect with multiple separate calls (performance anti-pattern)
-
Note INFO improvements
- Using render_callback in PHP instead of render file in block.json
- Missing viewScript/viewScriptModule in block.json (no frontend JS)
- apiVersion 2 (suggest upgrade to 3)
- Missing keywords in block.json
- Not using block hooks for auto-insertion opportunities
Report using output format below. If security concerns found (unescaped render output, user input in Interactivity API state), add note: "Security issues detected. Run /wp-sec-review for comprehensive security analysis." If plugin architecture issues found (init hook registration, ABSPATH check missing), add note: "Plugin architecture issues detected. Run /wp-plugin-review for comprehensive plugin review."
Source vs Build Review: Review src/ files for code patterns (developer intent). Flag if build/ directory is missing or stale (check index.asset.php timestamp vs src/ modification times). Do NOT review build/ files for code quality - they are compiled output.
File-Type Specific Checks
block.json (BLK-02, BLK-06, BLK-08, BLK-10)
apiVersion field:
- CRITICAL: Missing apiVersion → Block won't register correctly
- WARNING: apiVersion 1 or 2 → Upgrade to 3 for iframe isolation (WP 6.3+)
- Pattern:
"apiVersion": 3
name field:
- CRITICAL: Missing name → Block won't register
- CRITICAL: Invalid format (not "namespace/block-name") → Registration fails
- Pattern:
"name": "my-plugin/my-block" (lowercase, dashes, letters, numbers)
attributes field:
- CRITICAL: Invalid type (not string/number/boolean/object/array/integer/null) → Validation fails
- CRITICAL: source:'meta' → Deprecated, use useEntityProp hook instead
- WARNING: type doesn't match source data type → Attribute won't populate correctly
- Pattern: Validate type, source, selector, default combinations
- Sources: attribute, text, html, query (meta deprecated)
supports field:
- WARNING: Missing supports → Users can't customize color/spacing/typography
- INFO: Could add common supports (color, spacing, typography, align, anchor)
- Pattern: Object with nested configuration for each support type
editorScript/script/viewScript/viewScriptModule fields:
- WARNING: Invalid path format → Assets won't load
- Pattern:
"file:./index.js" relative to block.json location
- Note: viewScriptModule for Interactivity API (WP 6.5+)
render field:
- INFO: Dynamic blocks can use render file instead of render_callback
- Pattern:
"file:./render.php" relative to block.json location
$schema field:
- INFO: Missing $schema → Can't validate schema in IDE
- Pattern:
"$schema": "https://schemas.wp.org/trunk/block.json"
Edit function / edit.js (BLK-05, BLK-20)
useBlockProps usage:
- CRITICAL: useBlockProps() not called → Block won't render properly in editor
- CRITICAL: useBlockProps result not spread on wrapper → Missing block classes/attributes
- Pattern:
const blockProps = useBlockProps(); then <div { ...blockProps }>
Import patterns:
- WARNING: window.wp.* global access → Legacy pattern, breaks modern builds
- Pattern: GOOD:
import { useBlockProps } from '@wordpress/block-editor'; BAD: const { useBlockProps } = window.wp.blockEditor;
InspectorControls and BlockControls:
- INFO: Could add settings sidebar with InspectorControls
- INFO: Could add toolbar controls with BlockControls
- Pattern: InspectorControls for PanelBody/ToggleControl/SelectControl, BlockControls for AlignmentToolbar/ToolbarGroup
RichText usage:
- WARNING: RichText without tagName → May render incorrectly
- WARNING: RichText without value/onChange → Not controlled component
- Pattern:
<RichText tagName="p" value={ attributes.content } onChange={ ( content ) => setAttributes( { content } ) } />
InnerBlocks usage:
- INFO: Consider allowedBlocks to restrict nesting
- INFO: Consider template for default block structure
- Pattern:
<InnerBlocks allowedBlocks={ [ 'core/paragraph' ] } template={ [ [ 'core/heading' ] ] } />
useSelect/useDispatch performance:
- WARNING: Multiple separate useSelect calls → Performance degradation with many blocks
- Pattern: Combine selectors in single useSelect when reading multiple values
Internationalization:
- WARNING: Hardcoded strings without __() → Not translatable
- Pattern:
__( 'Text', 'text-domain' ) for all user-facing strings
Save function / save.js (BLK-05, BLK-07)
Static blocks (save returns JSX):
- CRITICAL: Missing useBlockProps.save() → Block validation error (apiVersion 3)
- WARNING: RichText without RichText.Content → Won't save rich text correctly
- WARNING: InnerBlocks without InnerBlocks.Content → Nested blocks won't save
- Pattern:
const blockProps = useBlockProps.save(); then <div { ...blockProps }>
Dynamic blocks (save returns null or InnerBlocks.Content):
- CRITICAL: Dynamic block with InnerBlocks but save returns null → Nested blocks lost (BLK-14)
- Pattern: If block uses InnerBlocks, save MUST return
<InnerBlocks.Content /> even for dynamic blocks
Deterministic save:
- WARNING: Math.random() or Date.now() in save → Block validation errors on re-save
- WARNING: Side effects in save → Unpredictable behavior
- Pattern: Save must return identical markup for identical attributes
Render callback / render.php (BLK-11)
ABSPATH check:
- WARNING: Missing defined( 'ABSPATH' ) || exit; → Direct file access possible
- Pattern: First line after <?php should be ABSPATH check
- Cross-reference: See wp-security-review for security depth
get_block_wrapper_attributes():
- WARNING: Manual class concatenation instead of get_block_wrapper_attributes() → Missing block supports
- Pattern:
$wrapper_attributes = get_block_wrapper_attributes(); then <div <?php echo $wrapper_attributes; ?>>
Output escaping:
- CRITICAL: Unescaped output → XSS vulnerability (CWE-79)
- CRITICAL: wp_kses_post() on $content from InnerBlocks → Breaks embeds (BLK-21)
- Pattern: esc_html() for text, esc_attr() for attributes, esc_url() for URLs, wp_kses_post() for trusted HTML (but NOT InnerBlocks $content)
- Cross-reference: See wp-security-review for comprehensive escaping patterns
Function parameters:
- $attributes: Array of block attributes
- $content: InnerBlocks HTML (if InnerBlocks used)
- $block: WP_Block instance with context and other metadata
- Pattern: Use all three parameters for full dynamic block functionality
Plugin main file / plugin.php
register_block_type():
- CRITICAL: Missing register_block_type() → Block won't register
- WARNING: Not hooked to 'init' → May register too early
- Pattern:
add_action( 'init', 'callback' ); then register_block_type( __DIR__ . '/build/block-name' );
Multi-block registration:
- WARNING: Single register_block_type() for multi-block plugin → Other blocks won't register
- Pattern: Call register_block_type() for each block's build directory
Plugin header and ABSPATH:
- Cross-reference: See wp-plugin-development for plugin header requirements and ABSPATH check
Block deprecation (BLK-09)
deprecated array:
- CRITICAL: Save function changed without deprecation → Block validation errors for existing content
- WARNING: Missing apiVersion in deprecation entry → Deprecation may not match
- Pattern: deprecated array with save + attributes for each version
migrate function:
- INFO: Could add migrate function for attribute schema changes
- Pattern:
migrate( attributes ) { return { ...attributes, newField: 'default' }; }
Ordering:
- WARNING: Deprecations ordered oldest first → WordPress checks newest first, performance issue
- Pattern: Newest deprecation listed FIRST in array
Interactivity API files (BLK-12)
WP 6.5+ version marker:
- INFO: Interactivity API requires WordPress 6.5+ → Add version check or plugin requirement
- Pattern: Check
Requires at least: 6.5 in plugin header
render.php directives:
- data-wp-interactive="namespace" → REQUIRED for Interactivity API scope
- wp_interactivity_state() → Server-side state initialization
- wp_interactivity_config() → Server-side configuration
- data-wp-context → Context provider for nested elements
- Directives: data-wp-bind, data-wp-on, data-wp-class, data-wp-style, data-wp-text, data-wp-watch, data-wp-init, data-wp-each
view.js (frontend store):
- WARNING: Import from window.wp.interactivity → Legacy pattern, use @wordpress/interactivity
- Pattern:
import { store } from '@wordpress/interactivity'; then store( 'namespace', { actions, state } );
Key distinction:
- Interactivity API = FRONTEND ONLY (view.js, render.php directives)
- Editor still uses React (edit.js)
- Don't confuse frontend state management with editor component state
Security crossover:
- WARNING: User input in wp_interactivity_state() without sanitization → XSS risk
- Cross-reference: See wp-security-review for input sanitization patterns
Block context (BLK-16)
providesContext (parent block):
- Pattern: In parent block.json:
"providesContext": { "myPlugin/keyName": "attributeName" }
- Namespace context keys: Use "myPlugin/keyName" format
usesContext (child block):
- Pattern: In child block.json:
"usesContext": [ "myPlugin/keyName" ]
- Access in edit:
function Edit( { context } ) { const value = context['myPlugin/keyName']; }
Surface-level checks
Block transforms (BLK-13 partial):
- INFO: Could add transforms for conversion from/to other blocks
- Pattern: from/to array in block registration
Block variations (BLK-13):
- INFO: Could add variations for preset configurations
- Pattern: variation picker, isDefault, scope properties
Block styles:
- INFO: Could register style variations in block.json or PHP
- Pattern: styles array in block.json or register_block_style() in PHP
Block patterns (BLK-18):
- Pattern: register_block_pattern() structure, categories, keywords
- Note: Patterns are multi-block layouts, different from variations (single block presets)
Block hooks (BLK-19):
- INFO: Could use blockHooks for auto-insertion (WP 6.4+)
- CRITICAL: Block hooks only work with dynamic blocks (save returns null)
- Pattern: blockHooks property in block.json
Block Bindings API (BLK-17):
- INFO: Could use bindings for dynamic attribute connections (WP 6.5+)
- Pattern: Surface-level detection only
@wordpress/scripts build config:
- WARNING: Missing @wordpress/scripts → No build toolchain
- WARNING: package.json missing build/start scripts → Can't compile blocks
- Pattern: Check package.json for "scripts": { "build": "wp-scripts build", "start": "wp-scripts start" }
Template lock:
- INFO: Could use templateLock on InnerBlocks for fixed layouts
- Pattern:
<InnerBlocks templateLock="all" /> prevents block addition/removal/reordering
Search Patterns for Quick Detection (BLK-22)
Use these rg commands for quick block scanning. Organized by severity. Cover BOTH PHP and JS/JSX files.
CRITICAL Patterns
rg -l --iglob 'block.json' . | xargs -I{} sh -c "rg -q '\"apiVersion\"\\s*:\\s*3' '{}' || echo '{}'"
rg -n "window\.wp\." . -g '*.{js,jsx}'
rg -n "function save|const save\s*=|save:\s*\(" . -g '*.{js,jsx}'
rg -n "wp_kses_post\s*\(\s*\$content\s*\)" . -g '*.php'
rg -n "InnerBlocks" . -g '*.{js,jsx}'
rg -n "return\s+null" . -g '*.{js,jsx}'
rg -n "\"source\"\s*:\s*\"meta\"" . -g 'block.json'
rg -n "register_block_type\s*\(" . -g '*.php'
WARNING Patterns
rg -l --iglob 'block.json' . | xargs -I{} sh -c "rg -q '\"supports\"' '{}' || echo '{}'"
rg -n "function Edit|export default function Edit|const Edit\s*=" . -g '*.{js,jsx}'
rg -n "title\s*:\s*['\"][A-Z]" . -g '*.{js,jsx}'
rg -l --iglob 'render.php' . | xargs -I{} sh -c "rg -q 'get_block_wrapper_attributes' '{}' || echo '{}'"
rg -l --iglob 'render.php' . | xargs -I{} sh -c "rg -q 'defined.*ABSPATH' '{}' || echo '{}'"
rg -n "Math\.random|Date\.now|new Date\(" . -g 'save.js'
rg -l --iglob 'block.json' . | xargs -I{} sh -c "rg -q '\"\\$schema\"' '{}' || echo '{}'"
rg -n "useSelect\s*\(" . -g '*.{js,jsx}'
INFO Patterns
grep -rn "render_callback" --include="*.php" .
grep -L "viewScript\|viewScriptModule" --include="block.json" .
grep -rn "\"apiVersion\": 2" --include="block.json" .
grep -L "\"keywords\"" --include="block.json" .
Note: Grep patterns for JavaScript require different regex than PHP patterns. Use --include="*.js" --include="*.jsx" for JS files, --include="*.php" for PHP files.
Block Context Detection
Context-aware review notes based on block distribution and loading context:
Single block plugin
Structure: One block.json at root or src/, single build output
Review adjustments: Standard review, no special considerations
Pattern: Plugin folder contains single src/ directory with index.js, edit.js, save.js
Multi-block plugin
Structure: Multiple blocks in src/block-one/, src/block-two/, each with block.json
Review adjustments:
- Check shared components in src/shared/ or src/components/
- Verify consistent naming conventions across all blocks
- Ensure build config handles all blocks (multiple entry points or wildcard)
- Verify register_block_type() called for each block's build directory
Pattern: Plugin folder contains multiple src/*/block.json files
Block library/collection
Structure: Published as npm package or WordPress.org plugin with multiple blocks
Review adjustments:
- Namespacing CRITICAL (all blocks must use consistent namespace)
- Check for consistent naming: "namespace/block-one", "namespace/block-two"
- Verify all blocks in same namespace
- Package.json should have "main" field pointing to build entry
Pattern: package.json has "name" field, published to npm or WordPress.org
Theme blocks
Structure: Registered in functions.php, block files in /blocks/ or /inc/blocks/
Review adjustments:
- Different loading context (theme activation vs plugin activation)
- Block may depend on theme.json settings (colors, spacing, typography)
- Brief note on theme.json integration, defer depth to Phase 4 (Theme Development)
- Verify blocks registered on 'init' or 'after_setup_theme' hook
Pattern: register_block_type() in functions.php, blocks in theme subdirectory
Quick Reference: Block Development Patterns (BLK-23)
Common block patterns organized by concern. All examples use WordPress coding standards (PHP: spaces in parentheses, array() not [], Yoda conditions; JS: tab indentation, camelCase, PascalCase for components).
block.json Schema
Complete schema with all fields annotated (apiVersion 3):
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "my-plugin/my-block",
"title": "My Block",
"category": "widgets",
"icon": "smiley",
"description": "A custom block example",
"keywords": [ "custom", "example" ],
"version": "1.0.0",
"textdomain": "my-plugin",
"attributes": {
"content": {
"type": "string",
"source": "html",
"selector": "p",
"default": ""
},
"showImage": {
"type": "boolean",
"default": false
}
},
"supports": {
"html": false,
"color": {
"background": true,
"text": true
},
"spacing": {
"margin": true,
"padding": true
},
"typography": {
"fontSize": true,
"lineHeight": true
},
"align": [ "wide", "full" ],
"anchor": true
},
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css",
"viewScriptModule": "file:./view.js"
}
Block Registration
PHP + JS registration pattern:
❌ BAD: Missing ABSPATH check, not hooked to init
<?php
function my_plugin_register_block() {
register_block_type( __DIR__ . '/build/my-block' );
}
my_plugin_register_block();
✅ GOOD: Complete registration with ABSPATH and init hook
<?php
defined( 'ABSPATH' ) || exit;
function my_plugin_register_blocks() {
register_block_type( __DIR__ . '/build/my-block' );
}
add_action( 'init', 'my_plugin_register_blocks' );
✅ GOOD: Multi-block registration
<?php
defined( 'ABSPATH' ) || exit;
function my_plugin_register_blocks() {
register_block_type( __DIR__ . '/build/block-one' );
register_block_type( __DIR__ . '/build/block-two' );
register_block_type( __DIR__ . '/build/block-three' );
}
add_action( 'init', 'my_plugin_register_blocks' );
Static Block Pattern
Edit with useBlockProps, save with useBlockProps.save, RichText + RichText.Content:
❌ BAD: Missing useBlockProps in edit and save
export default function Edit( { attributes, setAttributes } ) {
return (
<div className="my-block">
<input
value={ attributes.content }
onChange={ ( e ) => setAttributes( { content: e.target.value } ) }
/>
</div>
);
}
export default function save( { attributes } ) {
return (
<div className="my-block">
<p>{ attributes.content }</p>
</div>
);
}
✅ GOOD: Complete static block with useBlockProps and RichText
import { useBlockProps, RichText } from '@wordpress/block-editor';
export default function Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps();
return (
<div { ...blockProps }>
<RichText
tagName="p"
value={ attributes.content }
onChange={ ( content ) => setAttributes( { content } ) }
placeholder="Enter content..."
/>
</div>
);
}
import { useBlockProps, RichText } from '@wordpress/block-editor';
export default function save( { attributes } ) {
const blockProps = useBlockProps.save();
return (
<div { ...blockProps }>
<RichText.Content tagName="p" value={ attributes.content } />
</div>
);
}
Dynamic Block Pattern
Edit with useBlockProps, save returns null (or InnerBlocks.Content), render.php with get_block_wrapper_attributes and escaping:
❌ BAD: render callback without wrapper attributes, unescaped output
<?php
function my_plugin_render_callback( $attributes ) {
return '<div><p>' . $attributes['content'] . '</p></div>';
}
✅ GOOD: Complete dynamic block with proper escaping
<?php
defined( 'ABSPATH' ) || exit;
$wrapper_attributes = get_block_wrapper_attributes();
?>
<div <?php echo $wrapper_attributes; ?>>
<p><?php echo esc_html( $attributes['content'] ); ?></p>
</div>
export default function save() {
return null;
}
✅ GOOD: Dynamic block registered with render file
<?php
defined( 'ABSPATH' ) || exit;
function my_plugin_register_blocks() {
register_block_type( __DIR__ . '/build/my-block' );
}
add_action( 'init', 'my_plugin_register_blocks' );
InnerBlocks Pattern
allowedBlocks, template, templateLock, InnerBlocks.Content in save (even for dynamic blocks):
❌ BAD: Dynamic block with InnerBlocks but save returns null
import { useBlockProps, InnerBlocks } from '@wordpress/block-editor';
export default function Edit() {
const blockProps = useBlockProps();
return (
<div { ...blockProps }>
<InnerBlocks />
</div>
);
}
export default function save() {
return null;
}
✅ GOOD: Dynamic block with InnerBlocks saves nested content
import { useBlockProps, InnerBlocks } from '@wordpress/block-editor';
export default function Edit() {
const blockProps = useBlockProps();
const ALLOWED_BLOCKS = [ 'core/paragraph', 'core/image', 'core/heading' ];
const TEMPLATE = [
[ 'core/heading', { placeholder: 'Card Title' } ],
[ 'core/paragraph', { placeholder: 'Card content...' } ],
];
return (
<div { ...blockProps }>
<InnerBlocks
allowedBlocks={ ALLOWED_BLOCKS }
template={ TEMPLATE }
templateLock={ false }
/>
</div>
);
}
import { InnerBlocks } from '@wordpress/block-editor';
export default function save() {
return <InnerBlocks.Content />;
}
✅ GOOD: render.php uses $content parameter for InnerBlocks HTML
<?php
defined( 'ABSPATH' ) || exit;
$wrapper_attributes = get_block_wrapper_attributes();
?>
<div <?php echo $wrapper_attributes; ?>>
<h3><?php echo esc_html( $attributes['title'] ); ?></h3>
<?php echo $content;
</div>
useBlockProps
edit (useBlockProps()) and save (useBlockProps.save()), merging custom props:
❌ BAD: Missing useBlockProps
export default function Edit() {
return <div className="my-block">Content</div>;
}
function save() {
return <div className="my-block">Content</div>;
}
✅ GOOD: useBlockProps with custom props merged
import { useBlockProps } from '@wordpress/block-editor';
export default function Edit( { attributes } ) {
const blockProps = useBlockProps( {
className: 'my-custom-class',
style: { backgroundColor: attributes.bgColor },
} );
return <div { ...blockProps }>Content</div>;
}
function save( { attributes } ) {
const blockProps = useBlockProps.save( {
className: 'my-custom-class',
style: { backgroundColor: attributes.bgColor },
} );
return <div { ...blockProps }>Content</div>;
}
Attributes
type/source/selector/default patterns, attribute type matching:
❌ BAD: Type mismatch, no default, deprecated source
{
"attributes": {
"count": {
"type": "number",
"source": "text",
"selector": ".count"
},
"metaValue": {
"type": "string",
"source": "meta",
"meta": "my_meta_key"
}
}
}
✅ GOOD: Correct type/source matching, defaults, modern patterns
{
"attributes": {
"content": {
"type": "string",
"source": "html",
"selector": "p",
"default": ""
},
"count": {
"type": "number",
"source": "attribute",
"selector": ".count",
"attribute": "data-count",
"default": 0
},
"url": {
"type": "string",
"source": "attribute",
"selector": "a",
"attribute": "href",
"default": ""
},
"items": {
"type": "array",
"source": "query",
"selector": "li",
"query": {
"text": {
"type": "string",
"source": "text"
}
},
"default": []
}
}
}
✅ GOOD: Meta attribute using useEntityProp (not deprecated source)
import { useEntityProp } from '@wordpress/core-data';
export default function Edit() {
const [ meta, setMeta ] = useEntityProp( 'postType', 'post', 'meta' );
const value = meta.my_meta_key;
const updateMeta = ( newValue ) => {
setMeta( { ...meta, my_meta_key: newValue } );
};
}
Block Controls
InspectorControls for sidebar, BlockControls for toolbar, PanelBody, ToggleControl, SelectControl:
❌ BAD: Settings hardcoded in block markup, no sidebar controls
export default function Edit( { attributes, setAttributes } ) {
return (
<div>
<label>
Show Image:
<input
type="checkbox"
checked={ attributes.showImage }
onChange={ ( e ) => setAttributes( { showImage: e.target.checked } ) }
/>
</label>
</div>
);
}
✅ GOOD: InspectorControls for sidebar, BlockControls for toolbar
import { useBlockProps, InspectorControls, BlockControls, AlignmentToolbar } from '@wordpress/block-editor';
import { PanelBody, ToggleControl, SelectControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
export default function Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps();
return (
<>
<BlockControls>
<AlignmentToolbar
value={ attributes.align }
onChange={ ( align ) => setAttributes( { align } ) }
/>
</BlockControls>
<InspectorControls>
<PanelBody title={ __( 'Settings', 'my-plugin' ) }>
<ToggleControl
label={ __( 'Show featured image', 'my-plugin' ) }
checked={ attributes.showImage }
onChange={ ( showImage ) => setAttributes( { showImage } ) }
/>
<SelectControl
label={ __( 'Display style', 'my-plugin' ) }
value={ attributes.style }
options={ [
{ label: 'Default', value: 'default' },
{ label: 'Card', value: 'card' },
{ label: 'List', value: 'list' },
] }
onChange={ ( style ) => setAttributes( { style } ) }
/>
</PanelBody>
</InspectorControls>
<div { ...blockProps }>
{/* Block content */}
</div>
</>
);
}
Block Deprecation
deprecated array, save + attributes + migrate, apiVersion in entries, newest first:
❌ BAD: Save function changed without deprecation
function save( { attributes } ) {
const blockProps = useBlockProps.save();
return <div { ...blockProps }>{ attributes.content }</div>;
}
✅ GOOD: Deprecation entry for old save function
import { useBlockProps } from '@wordpress/block-editor';
const deprecated = [
{
apiVersion: 2,
attributes: {
content: { type: 'string' },
},
save( { attributes } ) {
return <div className="my-block">{ attributes.content }</div>;
},
},
{
apiVersion: 2,
attributes: {
content: { type: 'string' },
},
save( { attributes } ) {
return <p>{ attributes.content }</p>;
},
migrate( attributes ) {
return {
...attributes,
newField: 'default',
};
},
},
];
function save( { attributes } ) {
const blockProps = useBlockProps.save();
return <div { ...blockProps }>{ attributes.content }</div>;
}
export default {
edit: Edit,
save,
deprecated,
};
Interactivity API
data-wp-interactive, data-wp-bind, data-wp-on, store(), wp_interactivity_state(), frontend-only emphasis:
❌ BAD: Custom JavaScript for frontend interaction
<?php
?>
<div class="my-block">
<button id="toggle-button">Toggle</button>
<div id="content" style="display: none;">Hidden content</div>
</div>
<script>
document.getElementById('toggle-button').addEventListener('click', function() {
var content = document.getElementById('content');
content.style.display = content.style.display === 'none' ? 'block' : 'none';
});
</script>
✅ GOOD: Interactivity API with directives (WP 6.5+)
<?php
defined( 'ABSPATH' ) || exit;
wp_interactivity_state( 'myPlugin', array(
'isOpen' => false,
) );
$wrapper_attributes = get_block_wrapper_attributes();
?>
<div
<?php echo $wrapper_attributes; ?>
data-wp-interactive="myPlugin"
data-wp-context='{ "id": "<?php echo esc_attr( uniqid() ); ?>" }'
>
<button data-wp-on--click="actions.toggle">
<?php esc_html_e( 'Toggle', 'my-plugin' ); ?>
</button>
<div data-wp-bind--hidden="!state.isOpen">
<p><?php esc_html_e( 'Hidden content', 'my-plugin' ); ?></p>
</div>
</div>
import { store } from '@wordpress/interactivity';
store( 'myPlugin', {
state: {
isOpen: false,
},
actions: {
toggle: ( { state } ) => {
state.isOpen = ! state.isOpen;
},
},
} );
block.json configuration:
{
"viewScriptModule": "file:./view.js"
}
Note: Interactivity API is for FRONTEND only. Editor still uses React (edit.js).
Import Patterns
@wordpress/* package imports vs window.wp.* legacy access:
❌ BAD: window.wp. global access (legacy)*
const { registerBlockType } = window.wp.blocks;
const { useBlockProps } = window.wp.blockEditor;
const { __ } = window.wp.i18n;
✅ GOOD: @wordpress/ package imports (modern)*
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';
Block Supports
color, spacing, typography, align, anchor in block.json:
❌ BAD: Missing supports field
{
"name": "my-plugin/my-block",
"title": "My Block"
}
✅ GOOD: Complete supports configuration
{
"name": "my-plugin/my-block",
"title": "My Block",
"supports": {
"html": false,
"color": {
"background": true,
"text": true,
"gradients": true,
"link": true
},
"spacing": {
"margin": true,
"padding": true,
"blockGap": true
},
"typography": {
"fontSize": true,
"lineHeight": true,
"fontFamily": true,
"fontWeight": true
},
"align": [ "wide", "full" ],
"anchor": true
}
}
Block Variations
variation objects with attributes and innerBlocks:
import { registerBlockVariation } from '@wordpress/blocks';
registerBlockVariation( 'core/columns', {
name: 'three-columns-equal',
title: 'Three Columns (Equal)',
description: 'Three columns with equal width',
icon: 'columns',
isDefault: false,
scope: [ 'block' ],
attributes: {
columns: 3,
},
innerBlocks: [
[ 'core/column' ],
[ 'core/column' ],
[ 'core/column' ],
],
} );
Block Transforms
from/to patterns:
import { createBlock } from '@wordpress/blocks';
export default {
edit: Edit,
save,
transforms: {
from: [
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: ( { content } ) => {
return createBlock( 'my-plugin/my-block', {
content,
} );
},
},
],
to: [
{
type: 'block',
blocks: [ 'core/paragraph' ],
transform: ( { content } ) => {
return createBlock( 'core/paragraph', {
content,
} );
},
},
],
},
};
Block Context
providesContext/usesContext:
{
"providesContext": {
"myPlugin/userId": "userId",
"myPlugin/userName": "userName"
},
"attributes": {
"userId": { "type": "number" },
"userName": { "type": "string" }
}
}
{
"usesContext": [ "myPlugin/userId", "myPlugin/userName" ]
}
export default function Edit( { context } ) {
const userId = context['myPlugin/userId'];
const userName = context['myPlugin/userName'];
return (
<div>
<p>User: { userName } ({ userId })</p>
</div>
);
}
Block Hooks
blockHooks with dynamic blocks only:
❌ BAD: Block hooks with static block
{
"blockHooks": {
"core/post-content": "after"
}
}
function save() {
return <div>Content</div>;
}
✅ GOOD: Block hooks with dynamic block
{
"blockHooks": {
"core/post-content": "after"
},
"render": "file:./render.php"
}
function save() {
return null;
}
@wordpress/scripts
package.json scripts configuration:
❌ BAD: Missing build scripts
{
"scripts": {
"test": "echo \"No build toolchain configured\""
}
}
✅ GOOD: Complete @wordpress/scripts configuration
{
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start",
"lint:js": "wp-scripts lint-js",
"format": "wp-scripts format",
"packages-update": "wp-scripts packages-update"
},
"devDependencies": {
"@wordpress/scripts": "^27.0.0"
}
}
Severity Definitions (BLK-24)
| Severity | Definition | Examples |
|---|
| CRITICAL | Block won't render OR crashes editor OR causes block validation error | Missing apiVersion or using apiVersion 1/2 without migration path, invalid attribute type causing save validation error, save function mismatch without deprecation entry, missing useBlockProps.save() in apiVersion 3 block, InnerBlocks in edit but save returns null (not InnerBlocks.Content), wp_kses_post() on InnerBlocks $content parameter, window.wp.* access breaking modern build, missing register_block_type() call, deprecated source:'meta' attribute pattern |
| WARNING | Block works but has quality/compatibility issues OR non-standard patterns | Deprecated API usage (apiVersion 1/2 without critical issues), missing block supports (color, spacing, typography), no deprecation handler for changed save function, hardcoded strings without i18n in JS/JSX or PHP, multiple separate useSelect calls (performance issue), missing get_block_wrapper_attributes() in render.php, missing defined( 'ABSPATH' ) in PHP files, save function with side effects (Math.random, Date.now) |
| INFO | Best practice improvements OR optimization opportunities | Could use render PHP file instead of render_callback function, missing viewScript/viewScriptModule for frontend interactions, not using block.json $schema field, apiVersion 2 (upgrade to 3 available), missing keywords in block.json, block hooks opportunity for auto-insertion, could add block variations for common presets, missing template lock on fixed InnerBlocks layouts |
Output Format (BLK-24)
Report findings grouped by FILE (PHP and JS/JSX files intermixed by actual file path), with line numbers and severity labels. Use BAD/GOOD code pairs for each finding.
# WordPress Block Review: my-block-plugin
## FILE: src/index.js
### Line 3: WARNING - Legacy global access
window.wp.* access is legacy pattern. Use @wordpress/* package imports for modern build toolchain.
❌ **BAD:**
```javascript
const { registerBlockType } = window.wp.blocks;
✅ GOOD:
import { registerBlockType } from '@wordpress/blocks';
FILE: src/edit.js
Line 12: CRITICAL - Missing useBlockProps
useBlockProps() not called in edit function. Block won't render correctly in editor.
❌ BAD:
export default function Edit() {
return <div className="my-block">Content</div>;
}
✅ GOOD:
import { useBlockProps } from '@wordpress/block-editor';
export default function Edit() {
const blockProps = useBlockProps();
return <div { ...blockProps }>Content</div>;
}
FILE: src/save.js
Line 5: CRITICAL - Missing useBlockProps.save()
apiVersion 3 blocks require useBlockProps.save(). Block validation errors will occur.
❌ BAD:
function save() {
return <div className="my-block">Content</div>;
}
✅ GOOD:
import { useBlockProps } from '@wordpress/block-editor';
function save() {
const blockProps = useBlockProps.save();
return <div { ...blockProps }>Content</div>;
}
FILE: render.php
Line 15: CRITICAL - wp_kses_post on InnerBlocks content
Using wp_kses_post() on $content breaks embed blocks and oEmbed processing. InnerBlocks content is already sanitized.
❌ BAD:
<?php echo wp_kses_post( $content ); ?>
✅ GOOD:
<?php echo $content;
Line 1: WARNING - Missing ABSPATH check
Add ABSPATH check at top of file to prevent direct access.
❌ BAD:
<?php
$wrapper_attributes = get_block_wrapper_attributes();
✅ GOOD:
<?php
defined( 'ABSPATH' ) || exit;
$wrapper_attributes = get_block_wrapper_attributes();
FILE: block.json
Line 2: WARNING - apiVersion 2 (upgrade available)
apiVersion 2 still works but upgrade to 3 recommended for iframe editor isolation (WP 6.3+).
❌ BAD:
{
"apiVersion": 2
}
✅ GOOD:
{
"apiVersion": 3
}
Line 10: INFO - Missing $schema field
Add $schema field for IDE validation support.
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
...
}
SUMMARY
Total issues: 7
- CRITICAL: 3 (must fix - block won't render correctly)
- WARNING: 3 (quality/compatibility issues)
- INFO: 1 (best practice improvement)
Block validation risk: HIGH - Missing useBlockProps.save() will cause validation errors
Security note: Missing ABSPATH check detected. Run /wp-sec-review for comprehensive security analysis.
Plugin note: Block registration detected. Run /wp-plugin-review for plugin architecture review.
## Common Mistakes (BLK-25)
Patterns that look like issues but are NOT problems:
| Pattern | Why It's NOT a Problem | Context |
|---------|------------------------|---------|
| **Dynamic block save() returning null** | Server-side PHP renders output. save() doesn't need to return markup. | Correct for render_callback or render file usage |
| **InnerBlocks.Content without useBlockProps wrapper** | Valid for dynamic blocks that only need to persist nested blocks. | Dynamic blocks can return bare InnerBlocks.Content in save() |
| **viewScript not needed** | Block has no frontend JavaScript behavior. | Editor-only blocks or static HTML blocks don't need viewScript |
| **render_callback without return** | Valid if callback echoes output (though return is preferred). | WordPress handles both echo and return patterns |
| **Missing style/editorStyle in block.json** | Block uses theme defaults or has no custom styling. | Not all blocks need custom styles |
| **apiVersion 2 blocks** | Still work in WordPress 6.x+, just missing iframe isolation features. | Upgrade recommended but not critical |
| **Block without supports** | Valid for simple blocks that don't need color/spacing/typography. | Intentional for minimal blocks |
| **save() function with className in wrapper** | apiVersion 2 auto-injects classes. apiVersion 3 requires useBlockProps. | apiVersion-dependent behavior, not a bug |
| **window.wp.* in browser console** | Expected for debugging. Only @wordpress/* imports in source code matter. | Console access fine, source imports should use packages |
| **Interactivity API not used** | Blocks with no frontend interaction don't need Interactivity API. | Editor-only or static blocks work without frontend JS |
| **No block.json deprecation for attribute additions** | Adding new optional attributes doesn't break existing blocks. | Only save() markup changes need deprecation |
| **InnerBlocks without template** | Free-form nesting is valid. Template is optional. | Intentional when users should choose any blocks |
## Version Compatibility Reference
Quick reference for WordPress version requirements:
| Feature | WordPress Version | Notes |
|---------|-------------------|-------|
| block.json metadata support | 5.8+ | Single source of truth for block registration |
| apiVersion 2 | 5.6+ | Automatic wrapper class injection in save() |
| apiVersion 3 | 6.3+ | Iframe editor isolation, manual wrapper handling required |
| InspectorControls group prop | 6.2+ | Settings/Appearance tabs in sidebar |
| Block Hooks API | 6.4+ | Auto-insertion, dynamic blocks only |
| Interactivity API | 6.5+ | data-wp-* directives, viewScriptModule |
| viewScriptModule field | 6.5+ | ES module support for Interactivity API |
| Block Bindings API | 6.5+ | Dynamic attribute connections |
| useEntityProp hook | 5.9+ | Replacement for deprecated source:'meta' |
## Deep-Dive References
For advanced block development patterns, load these companion reference documents:
| Task | Reference to Load |
|------|-------------------|
| block.json schema validation, field-by-field reference, attribute type/source/selector patterns | `references/block-json-guide.md` |
| React/JSX editor component patterns, useBlockProps, RichText, InspectorControls, BlockControls, useSelect/useDispatch | `references/editor-patterns.md` |
| Server-side rendering, render_callback vs render file, get_block_wrapper_attributes, output escaping, $attributes/$content/$block parameters | `references/dynamic-blocks-guide.md` |
| Interactivity API directives (data-wp-*), wp_interactivity_state(), store() patterns, frontend state management | `references/interactivity-api-guide.md` |
**Note:** Reference docs provide deep-dive content. This SKILL.md is self-sufficient for standard block reviews.
**Security crossover:** When encountering security-relevant patterns (unescaped render output, user input in Interactivity API state, missing ABSPATH checks), this skill provides brief reminders but defers to wp-security-review for comprehensive security analysis. For detailed security patterns, use `/wp-sec-review` command.
**Plugin crossover:** When encountering plugin-level patterns (register_block_type() on init hook, ABSPATH checks, plugin headers), this skill provides brief mentions but defers to wp-plugin-development for plugin architecture depth. For detailed plugin architecture review, use `/wp-plugin-review` command.
