Building custom Gutenberg blocks is one of the most valuable skills for modern WordPress developers. In this article, we’ll create a real plugin from scratch called wp-custom-blocks.

The Gutenberg editor has transformed how we build content in WordPress. Instead of relying on shortcodes or page builders, we can now create reusable, dynamic blocks using modern JavaScript (React) and WordPress APIs.

In this tutorial, you’ll learn how to create your own custom block plugin and understand the core concepts behind it.

Prerequisites:

Before starting, make sure you have:

• WordPress installed locally


• Node.js and npm installed


• Basic knowledge of JavaScript and React


• A code editor (VS Code recommended)

Step 1: Create the Plugin

Open your terminal and run:

npx @wordpress/create-block wp-custom-blocks

This command scaffolds a complete plugin with build tools, configuration, and a sample block.

Step 2: Navigate to the Project

cd wp-custom-blocks

npm install

npm start

Now your development environment is running and watching for changes.

Step 3: Understand the Project Structure

The generated project includes:

src/

index.js

build/

block.json

package.json

• 
  src/ → source code (React)


• 
  build/ → compiled files


• 
  block.json → block configuration

Step 4: Create a Hero Block

Let’s create a custom block with editable content.

Create a folder:

src/blocks/hero/

Register the Block

js

import { registerBlockType } from '@wordpress/blocks';

import Edit from './edit';

import Save from './save';

registerBlockType('wpcb/hero', {

title: 'Hero Block',

category: 'design',

attributes: {

title: { type: 'string', default: 'Hero Title' },

text: { type: 'string', default: 'Hero description...' },

buttonText: { type: 'string', default: 'Click here' },

},

edit: Edit,

save: Save,

});

Step 5: Block Editor (Edit)

js

import { RichText } from '@wordpress/block-editor';

export default function Edit({ attributes, setAttributes }) {

return (

  <RichText

    tagName="p"

    value={attributes.text}

    onChange={(value) => setAttributes({ text: value })}

  />



  <RichText

    tagName="button"

    value={attributes.buttonText}

    onChange={(value) =>

      setAttributes({ buttonText: value })

    }

  />

</div>

);

}

Step 6: Save Component

js

import { RichText } from '@wordpress/block-editor';

export default function Save({ attributes }) {

return (

  <p>

    <RichText.Content value={attributes.text} />

  </p>



  <button>

    <RichText.Content value={attributes.buttonText} />

  </button>

</div>

);

}

Step 7: Import the Block

In src/index.js:

js

import './blocks/hero';

Step 8: Test in WordPress

1. Move the plugin folder to:
   wp-content/plugins/


2. Activate the plugin


3. Open the block editor


4. Search for Hero Block
   

Creating custom Gutenberg blocks is a powerful way to build modern WordPress experiences. With tools like @wordpress/create-block, the setup is easier than ever.

If you're serious about WordPress development, mastering block development is a must-have skill.