An Overview of the WordPress Create Block Script

Matt Watson

·

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 entered wholesome-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 to wcor wcltd.
  • 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

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
@wordpress/block output

@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 Front End

Create Block Script - Default Back 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

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

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.

,