The official WordPress Editor (Gutenberg) team have provided a neat little script for you to create a block plugin with their
@wordpress/create-block npm script.
This article gives an overview of the WordPress Create Block Script, along with details of what it outputs.
This article is for an older version of the Create Block Script
Although the theory can still be applied, some of the information in this article may no longer be compatible with the latest create block script. You can view our updated Create Block Script Guide here.
Running the Create Block Script
The official documentation gives you a few different parameters to pass into the
npm init @wordpress/block command.
For my setup I ran it in interactive mode by omitting the parameters. I entered the following command into my terminal (while
cd‘ed into my
npm init @wordpress/block
The Script asked me a few questions in order to help me build my block.
Wanting to create a starter block for a plugin idea that I have (‘Wholesome Notes’) I answered the questions as follows:
- The block slug used for identification (also the plugin and output folder name):
- I want my block to be called
Wholesome Notes, so I entered
- The internal namespace for the block name (something unique for your products):
- As this should be unique for all of my products I entered
wholesome-code, as this is my company name. In hindsight this would be better shorted to
- The display title for your block:
- I entered the title of the plugin,
- The short description for your block (optional):
- I wasn’t 100% sure what I wanted to write here, so I just entered some text that I intend on altering later.
- The dashicon to make it easier to identify your block (optional):
- Quickly bringing up the WordPress Dashicons resource, I chose
admin-commentsas it has a note style icon.
- The category name to help users browse and discover your block (use arrow keys):
- I chose
layout, although to be honest this type of block would probably need its own category. That is something that I can alter at a later date.
The Script then went ahead and installed all of the dependancies that it needed via npm (at this point, it just installs the
wp-scripts npm package as a dependancy).
Inspecting the Output
With the commands above, the WordPress Create Block Script gives you the following output:
The following is a breakdown of each of those files and folders.
- This is the root folder of the plugin, it has the same name as the one I entered for the ‘slug’ in the setup questions.
/srcfolder. These are enqueued via the main
- This PHP file is autogenerated when the
- This file is only generated when you are compiling the assets for development mode (IE you run
npm startand not
- This is the folder that contains all of the uncompiled assets for your plugin.
- This file contains useful presets for your IDE (Integrated Development Environment), such as Visual Studio Code.
- This file tells git to ignore certain files when you are committing to a git repository (such as GitHub).
- The styles in this file are output in the editor only, it is enqueued via the main
- This file contains all of the npm dependancies for the plugin, and the commands that you can run. Note that the plugin utilises
@wordpress/scripts) as its base, so initially the dependancies loaded are for that package.
- The styles in this file are output in the editor and on the front end of the site, they are enqueued via the main
Exploring the Plugin
After you have created your plugin, if you activate it and insert it into the editor it will look like the following screenshots (frontend and backend).
As you can see the block provides us with some basic output which we can easily amend to implement our own block.
As you can see from the screenshots, the example code in
editor.css implements a red boarder in the editor, whereas the examples styles in
styles.css are applied to both the front and backend.
The entry point to customise the newly created block is the
There is plenty of inline documentation in this file, explaining why certain functions are being imported such as
registerBlockType for the registration of the block and
__ for i18n text translation support.
It also gives you some very basic output for the
save functions that are passed into the block registration.
Note: In later versions of the script, these have been extracted out into their own files and included as modules in this file.
Building the Block
As per the create block npm documentation, you can use several commands in your terminal (from the root folder of your plugin), to do things like checking code quality, or update packages.
The main commands you will need to build the block will be
npm start to compile your plugin for development and
npm run build to compile the final version.
wp-scripts (from the
Behind the scenes
webpack to compile all of your assets into the
Extending the Create Block webpack Setup
The codebase for your block may span multiple files, or even have a number of sub-blocks, or contain complex styles. At times like these you may wish to extend the webpack setup that is built into
For more information see my article on how to extend the
wp-scripts webpack configuration, or checkout the Package Scripts section of the Block Editor Handbook for guidance.