Skip to main content
This guide will help you create your first custom WordPress block using the official @wordpress/create-block tool. You’ll have a working block in just a few minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js version 20.10.0 or above
  • npm version 10.2.3 or above
  • A WordPress installation (local or remote)
Use Node Version Manager (nvm) to easily manage Node.js versions on your system.

​
Create Your First Block

1

Scaffold the Block

Open your terminal and run the create-block command with your desired block name:
This creates a new WordPress plugin with a custom block named my-first-block. The command scaffolds all necessary files including:
  • PHP plugin file
  • JavaScript source files
  • Block configuration (block.json)
  • Build configuration
  • CSS styles
2

Navigate to the Plugin Directory

Change into your newly created plugin directory:
3

Start the Development Build

Start the development build process with watch mode:
This command runs a continuous build that automatically rebuilds your block whenever you make changes to the source files.
The development build includes additional warnings and helpful error messages. For production, use npm run build instead.
4

Install the Plugin in WordPress

Copy or symlink the entire plugin folder to your WordPress installation:
Then activate the plugin in your WordPress admin under Plugins.
5

Use Your Block

Create a new post or page in WordPress and click the block inserter (+). Search for “My First Block” and add it to your content.Congratulations! Your custom block is now working.

​
Understanding the Generated Files

The create-block tool generates a complete plugin structure:

​
Customizing Your Block

Let’s make a simple change to see the workflow in action:
1

Edit the Block Component

Open src/edit.js in your editor and modify the text:
src/edit.js
2

Watch the Auto-Rebuild

If npm start is running, your changes are automatically compiled. Check your terminal for confirmation.
3

Refresh the Editor

Reload the WordPress block editor to see your changes. The block should now display your updated text.

​
Using a Custom Namespace

By default, blocks are created with the create-block namespace. You should use your own unique namespace:
This creates a block named my-company/my-block instead of create-block/my-block.
Block names must be unique across all plugins and themes. Use a namespace that represents your company or project to avoid conflicts.

​
Available npm Scripts

Your scaffolded plugin includes several useful commands:

​
Next Steps

Now that you have a working block, explore more advanced topics:

Create Your First Block

Deep dive tutorial on block development

Block Editor Handbook

Complete documentation and API reference

Block Supports API

Add common features to your blocks

Development Environment

Set up a complete local development environment

​
Troubleshooting

The install scripts require Python to be installed. Download and install Python from python.org and ensure it’s in your system PATH.
  • Ensure the plugin is activated in WordPress
  • Check that npm start or npm run build completed successfully
  • Clear your browser cache and reload the editor
  • Verify npm start is running and watching for changes
  • Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
  • Check the browser console for JavaScript errors