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.
NOTE: 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 wp-content/plugins
folder):
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 enteredwholesome-notes
. - 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 towc
orwcltd
. - The display title for your block: I entered the title of the plugin,
Wholesome Notes
. - An Overview of the WordPress Create Block Script 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-comments
as 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.
Running npm init @wordpress/block
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:
- wholesome-notes
- build
- index.asset.php
- index.js
- index.js.map
- node_modules
- src
- index.js
- .editorconfig
- .gitignore
- editor.css
- package.json
- style.css
- wholesome-notes.php
- build
@wordpress/block output
The following is a breakdown of each of those files and folders.
wholesome-notes
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.
/build
This is the build folder. It contains all the JavaScript and PHP assets generated from the /src
folder. These are enqueued via the main wholesome-notes.php
loader file.
/build/index.assets.php
This PHP file is autogenerated when the /src
folder is compiled. It contains an array of all the WordPress Editor (Gutenberg) JavaScript decencies used by your plugin. It is enqueued via the main wholesome-notes.php
loader file.
/build/index.js
This is the main compiled JavaScript file, and is enqueued via the main wholesome-notes.php
loader file.
/build/index.js.map
This file is only generated when you are compiling the assets for development mode (IE you run npm start
and not npm run build
when you are compiling your assets. It is a helpful file for JavaScript debuggers to help identify file names and line numbers if errors occur.
/node_modules
This is the folder that all the JavaScript dependancies for your plugin are installed into.
/src
This is the folder that contains all of the uncompiled assets for your plugin.
/src/index.js
This is the main uncompiled JavaScript file for your WordPress Editor (Gutenberg) block. It initially contains all the logic for the block.
/.editorconfig
This file contains useful presets for your IDE (Integrated Development Environment), such as Visual Studio Code.
/.gitignore
This file tells git to ignore certain files when you are committing to a git repository (such as GitHub).
/editor.css
The styles in this file are output in the editor only, it is enqueued via the main wholesome-notes.php
loader file.
/package.json
This file contains all of the npm dependancies for the plugin, and the commands that you can run. Note that the plugin utilises wp-scripts
(@wordpress/scripts
) as its base, so initially the dependancies loaded are for that package.
/style.css
The styles in this file are output in the editor and on the front end of the site, they are enqueued via the main wholesome-notes.php
loader file.
/wholesome-notes.php
This is the main loader file for the plugin. Its name was set via the ‘slug’ that we entered in the initial setup script. It enqueues all of the JavaScript assets needed for the plugin.
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).
Create Block Script – Default Front End
Create Block Script – Default Back End
As you can see the block provides us with some basic output which we can easily amend to implement our own block.
Block CSS
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.
Block JavaScript
The entry point to customise the newly created block is the /src/index.js
file.
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.
Create Block index.js Inline Comments
It also gives you some very basic output for the edit
and 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.
Create Block index.js Edit and Save
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 @wordpress/scripts
npm package) is the main dependancy for your plugin. This dependancy abstracts all of the tooling for your block away, so you can just focus on building the JavaScript.
Behind the scenes wp-scripts
uses webpack
to compile all of your assets into the /build/index.js
file.
You can read more about wp-scripts
in the Block Editor Handbook and you can find out more about the webpack build setup in the ‘JavaScript Build Setup’ section of the Handbook.
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 wp-scripts
.
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.