Using @wordpress/create-block tool in Block Development

I personally almost never use starter themes for my WordPress projects, and usually I don’t rely on@wordpress/create-block when creating blocks (I prefer @wordpress/scripts, which we will uncover in the next lesson). But anyway, I think it is a great tool, in some cases, it could be really helpful, for example, when creating interactive blocks, so it is good to know how to use it.

As a result of this lesson, we will have a really simple block inside the Block Editor.

I also want to highlight the moment that by the end of this lesson, you will have a fully functional and correctly created block. Yes, the block literally does nothing, just displays the text, but you can explore its files, make some changes, and see what will happen in the Block Editor.

How to Use @wordpress/create-block?

It is as simple as running a single NPM command npx @wordpress/create-block.

If you don’t know what NPM is or how to run commands on your computer, you can always watch the video above, where I am guiding you through the whole process step by step and completely from scratch.

But now, we’re going to dive into some settings of the @wordpress/create-block tool.

First things first, you can run this tool in two modes: the interactive mode and the quick mode. Let’s talk about each one of them below.

Interactive mode

By default, the npx @wordpress/create-block command will run in the interactive mode, so it will ask you questions about your Gutenberg block right in the console:

Quick mode

But if you provide a block slug right after the command name, then the tool will not ask you anything during the installation process; it will just use the parameters you provided in the initial command.

For example:

npx @wordpress/create-block my-block --title My Test Block --short-description It is just a test block --category text

In the command above, we have:

• my-block – It is a block slug, and it is the only required thing we have to provide to run the tool in quick mode.
• --title <block title>,
• --short-description <block description>,
• --category <block category> – You can use one of the default categories: text, media, design, widget, theme and embed or a custom one.

But there are a bunch more parameters available to you in the @wordpress/create-block tool.

• --namespace <namespace> – By default, the tool uses a provided block slug as a namespace as well, for example, misha-block/misha-block, but you can provide a custom namespace for a block and change it, for example, to rudr/misha-block.
• --no-plugin – Though I didn’t use it here, it is quite useful when you don’t need to create a WordPress plugin for a block.
• --variant dynamic – Adding this command allows you to create a dynamic block instead of a static one. We will uncover dynamic blocks later in this course.
• --textdomain – A block text domain which we can use for block localization.
• --target-dir <directory> – By default, the files are going to be scaffolded in the current folder. For example, when we create a block as a custom WordPress plugin, we need to run the npx @wordpress/create-block command straight inside the /plugins folder, but this parameter allows you to scaffold a block inside a specific directory, which is a subdirectory of the current one.
• --template @wordpress/create-block-interactive-template – Allows you to scaffold an interactive block, for example. Some other templates are also available here.

More advanced parameters:

• --wp-scripts – This flag is enabled by default. What it does is simply tells the tool to set up the developer environment with @wordpress/scripts along with the scaffolded block.
• --no-wp-scripts – If you already have your developer environment ready and you just need to scaffold a block, you can use this flag.

Do I need to use @wordpress/create-block@latest?

What is the difference between these two commands: npx @wordpress/create-block and npx @wordpress/create-block@latest?

Actually, if you have never used this command before and you’re just starting out, you can just don’t think about it.

Otherwise, if, let’s say, a year ago or something you created a Gutenberg block and installed all the packages at that time, and now when you try to run the npx @wordpress/create-block command, you get a bunch of errors. It means, that the cached versions of some packages or templates are trying to be used. In that case, you need to install the latest ones by using @latest at the end.

Starter Block Files Structure

Below are all the files that are about to be created by the tool:

build/index.css, build/style-index.css, src/editor.scss, src/style.scss – These are block CSS, as you could’ve guessed. There is going to be a separate tutorial in this course fully covering that.

edit.js and save.js – as well as when you’re creating a WordPress theme, you don’t put everything in functions.php file, you don’t need to put the entire code of your custom Gutenberg block in src/index.js file, you can use import and export for that. We will learn more about these files in this lesson.

Gutenberg Block Development

Misha Rudrastyh

Hey guys and welcome to my website. For more than 10 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X