Since the introduction of the Gutenberg editor in WordPress 5.0, the landscape of WordPress development has shifted dramatically from PHP-centric templates to modern, JavaScript-driven component architectures. While page builders like Elementor remain popular, building native custom Gutenberg blocks gives you unmatched performance, cleaner code, and a seamless editing experience for your clients. In this step-by-step guide, we will walk through the modern workflow of creating your very first custom Gutenberg block from scratch.

1. The Modern Block Development Toolkit

Before writing a single line of code, you need to set up your local development environment. Modern Gutenberg development relies on Node.js and npm to compile modern JavaScript (ES6+ and React) into browser-compatible code. Here is what you need installed on your machine:

• Node.js & npm: Ensure you have the latest LTS version installed.
• Local WordPress Environment: Tools like LocalWP, DevKinsta, or Docker make it easy to run WordPress locally.
• Code Editor: VS Code is highly recommended for its excellent JavaScript and React extension ecosystem.

Historically, setting up webpack, Babel, and register scripts manually was a developer’s nightmare. Fortunately, the official WordPress developer team now maintains a scaffolding tool called @wordpress/create-block. This tool generates all the necessary files, build configurations, and plugin structures with a single command.

2. Generating Your First Block Scaffold

Open your terminal, navigate to your local WordPress installation’s plugins directory (e.g., /wp-content/plugins/), and run the following command:

npx @wordpress/create-block my-first-block

This command pulls the latest scaffolding template, installs the necessary npm packages, and creates a new plugin directory named my-first-block. Once the process finishes, navigate into your new directory:

cd my-first-block

Understanding the Block Directory Structure

Inside your newly generated plugin, you will find several critical files and folders:

• block.json: The metadata configuration file for your block. It defines the name, title, category, icon, and attributes.
• src/: This is where your development files live. It contains index.js, edit.js, save.js, and stylesheet files.
• build/: The compiled, production-ready code. WordPress actually reads from this directory, not the src/ directory.

3. Configuring the Block Metadata

Let’s open src/block.json. This file is the single source of truth for your block. We will add custom attributes to store our block’s data. Let’s modify it to include an attribute for a custom text message:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "create-block/my-first-block",
  "version": "0.1.0",
  "title": "My First Block",
  "category": "widgets",
  "icon": "smiley",
  "description": "An awesome custom Gutenberg block.",
  "attributes": {
    "content": {
      "type": "string",
      "source": "html",
      "selector": "p"
    }
  },
  "supports": {
    "html": false
  },
  "textdomain": "my-first-block",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

4. Customizing the Block: Edit vs. Save

Gutenberg blocks use a split rendering model. The block editor requires an Edit component (what the editor sees in the admin panel) and a Save component (what is rendered on the front end of the website).

The Edit Component

Open src/edit.js. We will use the RichText component from the @wordpress/block-editor package. This allows users to type and format content directly within the block.

import { useBlockProps, RichText } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit({ attributes, setAttributes }) {
	const { content } = attributes;

	const onChangeContent = (newContent) => {
		setAttributes({ content: newContent });
	};

	return (
		

			
		
	);
}

The Save Component

Now, let’s update src/save.js to output the saved content on the front end. The RichText.Content component is used to securely display block attributes.

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

export default function Save({ attributes }) {
	const { content } = attributes;

	return (
		

			
		
	);
}

5. Compiling and Testing Your Block

With your source files customized, it is time to build your block. Run the following command in your terminal to start the development compiler. This watch script automatically rebuilds your block every time you save a file:

npm run start

Now, follow these steps to test your creation:

1. Log in to your local WordPress dashboard.
2. Navigate to Plugins > Installed Plugins.
3. Locate “My First Block” and click Activate.
4. Create a new post or page.
5. Click the + icon and search for “My First Block” or locate the Smiley icon.
6. Add the block, type some custom text, and publish the post to see it render perfectly on the front end.

Conclusion

Congratulations! You have just built your very first custom Gutenberg block using modern WordPress development tools. By leveraging the @wordpress/create-block scaffold, you bypassed complex build configurations and jumped straight into writing React-based components. From here, you can explore adding Inspector Controls (block settings sidebar), media uploaders, or custom styles to make your blocks truly unique. Keep experimenting, and happy coding!