Add Block

Once the name is confirmed, apply the find-plugin skill to determine whether:

• WordPress Core already provides this block or equivalent functionality (check the block inserter's built-in blocks and block patterns).
• A well-maintained plugin on WordPress.org already ships this block.

Only proceed to the steps below if Core and existing plugins do not cover the need, or if the user has explicitly agreed to build a custom block after reviewing the recommendation.

Step 1 — Gather remaining information

Step 2 — Locate the blocks directory

Look for an existing block registration pattern in the target package. Typical location:

src/blocks/<block-name>/       (or src/<block-name>/ depending on plugin structure)
    block.json
    block.php                  (dynamic: registration + render via namespaced functions)
    edit.js
    index.js
    save.js                    (omit if dynamic)
    style.scss                 (front-end styles)
    editor.scss                (editor-only styles)
    view.js                    (only if frontend interactivity is needed)

Read the plugin's main PHP file to confirm the PHP namespace and how blocks are registered/loaded.

Step 3 — Create block files

block.json

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "<vendor>/<block-name>",
  "version": "1.0.0",
  "title": "<Block Title>",
  "category": "<category>",
  "description": "",
  "supports": {
    "html": false,
    "align": ["wide", "full"]
  },
  "attributes": {},
  "textdomain": "<plugin-slug>",
  "editorScript": "file:index.js",
  "editorStyle":  "file:index.css",
  "style":        "file:style-index.css"
}

• For dynamic blocks, omit "render" — the render callback is registered in block.php.
• If the block needs frontend interactivity, add "viewScript": "file:view.js" (omit otherwise).
• Add attributes as needed for the block's content.

block.php (dynamic blocks only)

<?php
/**
 * Block: <Block Title>
 *
 * @package <PluginNamespace>
 */

declare( strict_types=1 );

namespace <PluginNamespace>\Blocks\<BlockNamePascal>;

/**
 * Register block.
 */
function register_block(): void {
	register_block_type_from_metadata(
		__DIR__,
		[
			'render_callback' => __NAMESPACE__ . '\\render_block',
		]
	);
}
add_action( 'init', __NAMESPACE__ . '\\register_block' );

/**
 * Render block.
 *
 * @param array<string, mixed> $attributes Block attributes.
 * @param string               $content    Block inner content.
 * @return string
 */
function render_block( array $attributes, string $content ): string {
	$wrapper_attributes = get_block_wrapper_attributes();

	ob_start();
	?>
	<div <?php echo $wrapper_attributes; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>>
		<?php // Block output here ?>
	</div>
	<?php
	return ob_get_clean() ?: '';
}

• Match namespace to the plugin's existing namespace (e.g. ProjectBase\BlockLibrary\Blocks\HeroBanner).
• Always use get_block_wrapper_attributes() for the wrapper element.
• Always use ob_start()/ob_get_clean() for template rendering.
• Escape all output: esc_html(), esc_attr(), esc_url(), wp_kses_post().

index.js

/**
 * WordPress dependencies
 */
import { registerBlockType } from '@wordpress/blocks';

/**
 * Internal dependencies
 */
import metadata from './block.json';
import Edit from './edit';
import save from './save';   // omit for dynamic blocks

registerBlockType( metadata.name, {
	edit: Edit,
	save,                     // omit for dynamic blocks
} );

edit.js

/**
 * WordPress dependencies
 */
import { useBlockProps, RichText, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

/**
 * @param {Object} props Block props.
 * @return {JSX.Element} Block editor UI.
 */
export default function Edit( { attributes, setAttributes } ) {
	const { title } = attributes;
	const blockProps = useBlockProps();

	return (
		<>
			<InspectorControls>
				<PanelBody title={ __( 'Settings', '<text-domain>' ) }>
					{ /* Add controls here */ }
				</PanelBody>
			</InspectorControls>
			<div { ...blockProps }>
				<RichText
					tagName="h2"
					value={ title }
					onChange={ ( value ) => setAttributes( { title: value } ) }
					placeholder={ __( 'Add a title…', '<text-domain>' ) }
				/>
			</div>
		</>
	);
}

save.js (static blocks only)

/**
 * WordPress dependencies
 */
import { useBlockProps, RichText } from '@wordpress/block-editor';

/**
 * @param {Object} props Block props.
 * @return {JSX.Element} Saved block markup.
 */
export default function save( { attributes } ) {
	const { title } = attributes;
	return (
		<div { ...useBlockProps.save() }>
			<RichText.Content tagName="h2" value={ title } />
		</div>
	);
}

view.js (only if frontend interactivity is needed)

// Frontend behaviour for <Block Title> block
document.querySelectorAll( '.wp-block-<vendor>-<block-name>' ).forEach( ( block ) => {
	// Initialise block behaviour
} );

Step 4 — Verify block auto-discovery

Open the plugin's main PHP file and confirm it loads blocks via glob:

foreach ( glob( __DIR__ . '/build/*/block.php' ) as $block ) {
    require_once $block;
}

If the glob pattern is missing, add it. If the plugin uses a different registration pattern (e.g. a BlockRegistrar class), follow that pattern instead.

Step 5 — Build and lint

cd packages/plugins/<plugin-slug>
npm run build        # or from root: npm run build
npm run lint:js
npm run lint:css
composer lint

Confirm the block appears in build/<block-name>/ after the build.

Conventions

• Import grouping: Keep JS import statements grouped: WordPress core → internal. The @wordpress/dependency-group ESLint rule is enforced
• Block wrapper: Always use get_block_wrapper_attributes() in PHP render — this enables block spacing, align, and custom className support
• No jQuery: Use @wordpress/* packages or native DOM APIs

Output

When done, the following files exist under src/<block-name>/:

• block.json — block metadata
• block.php — PHP server-side render + registration (dynamic blocks)
• index.js — block registration entry point
• edit.js — block editor component
• save.js — static save output (static blocks only)
• view.js — (optional) frontend script

After npm run build, the block appears in build/<block-name>/ and is loadable in the WordPress editor. Lint passes with no errors.