How to Develop a Simple Gutenberg Block in WordPress

If you’ve ever wanted to extend your WordPress site beyond existing plugins or themes, Gutenberg blocks are your playground. Gutenberg (or the WordPress block editor) allows developers to create powerful, reusable, and interactive content blocks using React and modern JavaScript.

In this tutorial, we’ll walk you through creating a simple “Hello World” Gutenberg block from scratch — complete with folder structure, code snippets, and explanations.

🏗️ Prerequisites

Before you begin, make sure you have:

• WordPress 6.x or later
• Node.js (v14+) and npm installed
• A code editor like VS Code
• Basic knowledge of JavaScript and PHP

🗂️ Step 1: Set Up Your Plugin Folder

Inside your WordPress wp-content/plugins directory, create a new folder named:

my-first-gutenberg-block

Then, create the main plugin file inside it:

my-first-gutenberg-block.php

Add the plugin header:

<?php
/**
 * Plugin Name: My First Gutenberg Block
 * Description: A simple example Gutenberg block.
 * Author: Sufiyan Khan
 * Version: 1.0.0
 */

defined('ABSPATH') || exit;

// Enqueue block assets
function mfgb_enqueue_block() {
    wp_register_script(
        'mfgb-block',
        plugins_url('build/index.js', __FILE__),
        array('wp-blocks', 'wp-element', 'wp-editor', 'wp-components')
    );

    register_block_type('mfgb/hello-world', array(
        'editor_script' => 'mfgb-block'
    ));
}
add_action('init', 'mfgb_enqueue_block');

This code registers a new Gutenberg block script and hooks it into WordPress.

⚙️ Step 2: Initialize Your Block Project

Inside your plugin folder, run the following command:

npm init -y
npm install @wordpress/scripts --save-dev

Then, in your package.json, add a build script:

"scripts": {
  "build": "wp-scripts build",
  "start": "wp-scripts start"
}

This will let you compile modern ESNext and JSX code easily.

🧱 Step 3: Create the Block Files

Inside the plugin folder, create the following structure:

my-first-gutenberg-block/
├── build/
├── src/
│   └── index.js
└── my-first-gutenberg-block.php

💻 Step 4: Write the Block Code

Open src/index.js and add:

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';

registerBlockType('mfgb/hello-world', {
    title: 'Hello World Block',
    icon: 'smiley',
    category: 'widgets',

    edit() {
        const blockProps = useBlockProps();
        return (
            <div {...blockProps}>
                <h3>Hello from the Editor! 👋</h3>
                <p>You can edit this block text in real-time.</p>
            </div>
        );
    },

    save() {
        const blockProps = useBlockProps.save();
        return (
            <div {...blockProps}>
                <h3>Hello from the Frontend! 👋</h3>
                <p>This is a static Gutenberg block output.</p>
            </div>
        );
    },
});

✅ This defines both editor view (edit) and frontend view (save) of the block.

⚡ Step 5: Build Your Block

Run the build process:

npm run build

This will generate a compiled index.js inside the build folder — the one registered in your PHP file earlier.

Now go to your WordPress admin → Plugins → Activate “My First Gutenberg Block”.

🧩 Step 6: Use the Block in the Editor

1. Create or edit a page/post.
2. Click “Add Block (+)”.
3. Search for Hello World Block.
4. Add it to your page.

You’ll see your message rendered in both the editor and frontend — congrats, you’ve built your first Gutenberg block! 🎉

🧠 Bonus: Add Editable Text Fields

Let’s make it more dynamic. Replace the edit() function with this:

import { __ } from '@wordpress/i18n';
import { useState } from '@wordpress/element';
import { useBlockProps, RichText } from '@wordpress/block-editor';

registerBlockType('mfgb/hello-world', {
    title: __('Hello World Block', 'mfgb'),
    icon: 'smiley',
    category: 'widgets',

    attributes: {
        message: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
    },

    edit({ attributes, setAttributes }) {
        const blockProps = useBlockProps();
        const { message } = attributes;

        return (
            <div {...blockProps}>
                <RichText
                    tagName="p"
                    onChange={(value) => setAttributes({ message: value })}
                    value={message}
                    placeholder="Write your message here..."
                />
            </div>
        );
    },

    save({ attributes }) {
        const blockProps = useBlockProps.save();
        const { message } = attributes;

        return (
            <div {...blockProps}>
                <RichText.Content tagName="p" value={message} />
            </div>
        );
    },
});

Now you can type directly into the editor and save custom text — your first editable Gutenberg block.

🚀 Wrapping Up

You’ve just learned:
✅ How to register a block with PHP
✅ How to build the block with @wordpress/scripts
✅ How to render editable fields with RichText

From here, you can expand your block with:

• Custom attributes
• Inspector controls
• Stylesheets (editor.css and style.css)
• Dynamic PHP rendering

✨ Final Thoughts

Creating custom Gutenberg blocks gives you full control over how your WordPress content looks and behaves — and it’s easier than ever thanks to the @wordpress/scripts package.

Whether you’re developing for clients or extending your own site, understanding Gutenberg development is an essential modern WordPress skill.