Using the create-block Tool

Hey there, and welcome to Learn WordPress.

In this tutorial, you’re going to learn how to use the create-block tool to scaffold a new block plugin. In this video, we will cover what the create-block tool is, what software you need to use create-block, how to scaffold a new block using create-block, and the code generated by create-block.

Create-block is an official command line tool developed by WordPress contributors to scaffold or create a new block plugin. It generates everything you need to start a new blog plugin and integrates a modern built setup with no configuration. You can read more about create-block by visiting the Block Editor handbook in the WordPress developer resources page under Reference Guides -> Packages -> @wordpress/create-block.

in order to use the create-block tool, you’re going to need a local WordPress install, a terminal to run commands, and Node.js and npm. You can use any local WordPress install you’re comfortable with, like LocalWP or DesktopServer. If you don’t already have a local WordPress install, please take a look at the Local WordPress Installations for Beginners tutorial at learn.wordpress.org.

If you’re running Mac OS or any Linux operating system, you can use the built-in terminal. For Windows users, we recommend installing and using PowerShell which you can find by going to microsoft.com/powershell.

Finally, you need to install Node.js, which also installs npm. The create-block tool will work with any stable version of Node.js greater than version 12. However, depending on your development requirements, you might need to be able to switch Node.js versions quickly between projects. Fortunately, you can do this using the open source node version manager, also known as nvm. To find this, you can go to nvm.sh which will direct you to the GitHub page. The great thing about using nvm is if your version requirements change, it’s very easy to update your Node.js version using nvm. For the purposes of this tutorial, we’ll install the same version needed for core Block Development, which is listed in the Block Editor handbook on the Getting Started development environment page.

Currently, it’s recommended to install Node.js version 14. If you’re running macOS, or Linux, you can open your default terminal application and install nvm by running the npm install script which you copy from the nvm documentation.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Once npm is installed, you need to close your terminal and reopen it.

Then you can use the nvm install command to install the Node.js and npm versions you need.

nvm install 14

If you’re on a Windows machine, you will need to install the Chocolatey package manager for Windows to install nvm. First open PowerShell with administrative privileges by right-clicking on the PowerShell menu item and selecting Run as Administrator. Then browse to the Chocolatey setup documentation and scroll down to the Install with PowerShell instructions. Copy the instructions and right-click in the PowerShell window to paste them.

Once Chocolatey is installed, use the following command to install nvm:

choco install -y nvm

Once nvm is installed, use the nvm install command to install the required Node.js and npm versions;

nvm install 14

Finally, run the nvm use command to use the version of Node js and npm you just installed.

nvm use 14.20.0

Now you’re ready to use the create-block tool to create your first block. In your terminal change the directory to the WP content plugins directory of your local WordPress installation. In my case, it’s:

cd development/websites/wordpress/wp-content/plugins

Then run the create-block command and pass a plugin slug to this command. The slug is the unique name of the plugin.

npx @wordpress/create-block wp-learn-todo

This will create a new plugin in the wp-learn-todo directory, install any required packages, and create the necessary files. You’ll notice we didn’t have to install the create-block package. The npx command allows us to run the package from where it’s hosted in the cloud.

Once the new plugin is scaffolded you should have a new plugin folder in your WordPress install named after the slug passed to create-block.

There it is wp-learn-todo. Let’s take a look at the most important directories and files in this plugin.

The build directory is the location where the final block asset files will be built for distribution. node_modules contains any node packages or modules you need for development. The src or source directory is where you will do most of your coding all of your block load lives here. The package.json is the file that determines what packages your code needs. The readme.txt is a file that is used by the WordPress.org plugin repository to manage your plugin. And the wp-learn-todo.php file is the main plugin file that tells WordPress this is a plugin.

If we open WordPress and go to the Block Editor, we should be able to add this block. First, we’ll need to enable the block, and learn-todo is activated. Let’s go and create a new post and add a new block. There it is. At the moment it just contains a paragraph with some text.

And that wraps up this tutorial on using create-block. If you’re ready to start building custom blocks, check out the Adding Block Support to an Existing Plugin tutorial. For more WordPress developer tutorials, visit learn.wordpress.org.

Happy coding.