Using the create-block Tool
The WordPress create-block tool allows you to quickly scaffold a new block plugin.
In this lesson, you will learn what you need to get started with create-block, how to use it, and review the code it generates.
Timestamps
- Introduction: 0:00 – 1:04
- Software requirements: 1:04 – 2:07
- Installing nvm and Node/npm on macOS/Linux: 2:07 – 3:54
- Installing nvm and Node/npm on Windows: 3:54 – 5:14
- Using create-block to scaffold a block: 5:14 – 8:46
Learning outcomes
- Learn about what the create-block tool is
- Understand what software is required to use create-block
- Learn how to install any required software
- Review the code created by create-block
Comprehension questions
- What is the create-block tool and what is it used for?
- What tools and software are needed to use create-block?
- What is the command run to use create-block?
- What is the name of the directory that create-block creates for the final block files?
Video Transcript
View transcript
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.
Introduction
In this lesson, you’re going to learn about a command line tool called Create Block, and how you can use this tool to scaffold a new block plugin.
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 block plugin and integrates a modern build setup with no configuration.
You can read more about create-block by visiting the Block Editor handbook page.
Requirements
In order to use the create-block tool, you’re going to need a local WordPress install, a terminal to run commands, as well as Node.js and npm.
You can use any local WordPress install you’re comfortable with. 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 are running MacOS and or any Linux operating system, you can use the built-in terminal. For Windows users, we recommend installing and using PowerShell.
Finally, you need to install Node.js, which also installs the npm package manager:
- Node.js – https://nodejs.org/en/
- npm package manager – https://www.npmjs.com/
It’s important to make sure you use the right version of Node.js. Fortunately, you can do this using the open-source node version manager, also known as nvm.
The great thing about using nvm, is if your version requirements change, it’s very easy to update your Node.js version using nvm.
Installation
If you are using MacOS or Linux, you can open your default terminal application, and install nvm by running the nvm install script, copied from the nvm documentation.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
Once it is installed, you can use the nvm install command to install the Node.js and npm versions you need.
nvm install 14
If you are on a Windows machine, you will need to install the Chocolatey package manager for Windows to install nvm. More specificially, you must install the Chocolatey CLI for PowerShell
First open Powershell with administrator permissions by right clicking on the Powershell menu item and selecting Run as administrator.
Browse to the Chocolatey CLI setup documentation, and scroll down to the “Install with PowerShell” Instructions.
Copy the instructions and right click in the Powershell window to paste them.
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
Hit the Enter key to run the command
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 Nodejs and npm versions.
nvm install 14
Finally run the nvm use command to use the version of Node.js you just installed.
Using Create Block
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.
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.
Once the new plugin is scaffolded, you should have a new plugin folder in your WordPress install, named after the slug you passed to create-block.
The most important directories and files:
- build – this is the location where the final block asset files will be built for distribution
- node_modules – any node packages/modules you need for development
- src – the source directory, where you will do most of your coding. All your block code lives here.
- Package.json – the file that determines what packages your code needs
- Readme.txt – the file that is used by the WordPress.org plugin repository
- wp-learn-todo.php – the main plugin file that tells WordPress this is a plugin
Activate this plugin via the WordPress dashboard and if you open the block editor, you can add the WP Learn Todo block, which at the moment just contains a paragraph with some text.
And that wraps up this lesson on using Create Block.
To learn how to take this code and use it to convert a shortcode into a block, why not watch the Converting a Shortcode into a Block tutorial?
Additional Resources
- https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/
- https://learn.wordpress.org/tutorial/local-wordpress-installations-for-beginners/
- https://microsoft.com/powershell
- https://github.com/nvm-sh/nvm/blob/master/README.md
- https://docs.chocolatey.org/en-us/choco/setup